Subsections

10.2 The list of functions

Each user function is presented within it's own subsection with the documentation broken into multiple parts: the synopsis, the default arguments, and the sections from the function's docstring.

10.2.1 The synopsis

The synopsis presents a brief description of the function. It is taken as the first line of the docstring when browsing the help system.

10.2.2 Defaults

This section lists all the arguments taken by the function and their default values. To invoke the function type the function name then in brackets type a comma separated list of arguments.

The first argument printed is always `self' but you can safely ignore it. `self' is part of the object oriented programming within Python and is automatically prefixed to the list of arguments you supply. Therefore you can't provide `self' as the first argument even if you do try.

10.2.3 Docstring sectioning

All other sections are created from the sectioning of the user function docstring.





10.2.4 align_tensor.copy()

10.2.4.1 Synopsis

Function for copying alignment tensor data.

10.2.4.2 Defaults

align_tensor.
[0]
[0]copy
(
[0]self, tensor_from=
[0]None, pipe_from=
[0]None, tensor_to=
[0]None, pipe_to=
[0]None)

10.2.4.3 Keyword Arguments

tensor_from: The identification string of the alignment tensor to copy the data from.

pipe_from: The name of the data pipe to copy the alignment tensor data from.

tensor_to: The identification string of the alignment tensor to copy the data to.

pipe_to: The name of the data pipe to copy the alignment tensor data to.

10.2.4.4 Description

This function will copy the alignment tensor data to a new tensor or a new data pipe. The destination data pipe must not contain any alignment tensor data corresponding to the tensor_to label. If the pipe_from or pipe_to arguments are not supplied, then both will default to the current data pipe. Both the tensor_from and tensor_to arguments must be supplied.

10.2.4.5 Examples

To copy the alignment tensor data corresponding to `Pf1' from the data pipe `old' to the current data pipe, type one of:


relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]`Pf1', `old')


relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]tensor_from=
[0]
[0]`Pf1', pipe_from=
[0]
[0]`old')

To copy the alignment tensor data corresponding to `Otting' from the current data pipe to the data pipe new, type one of:


relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]`Otting', pipe_to=
[0]
[0]`new')


relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]tensor_from=
[0]
[0]`Otting', pipe_to=
[0]
[0]`new')

To copy the alignment tensor data of `Otting' to that of `Otting new', type one of:


relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]`Otting', tensor_to=
[0]
[0]`Otting new')


relax> align_tensor.
[0]
[0]
[0]copy(
[0]
[0]tensor_from=
[0]
[0]`Pf1', tensor_to=
[0]
[0]`Otting new')





10.2.5 align_tensor.delete()

10.2.5.1 Synopsis

Function for deleting alignment tensor data.

10.2.5.2 Defaults

align_tensor.
[0]
[0]delete
(
[0]self, tensor=
[0]None)

10.2.5.3 Keyword Arguments

tensor: The alignment tensor identification string.

10.2.5.4 Description

This function will delete the specified alignment tensor data from the current data pipe.





10.2.6 align_tensor.display()

10.2.6.1 Synopsis

Function for displaying the alignment tensor information.

10.2.6.2 Defaults

align_tensor.
[0]
[0]display
(
[0]self, tensor=
[0]None)

10.2.6.3 Keyword Arguments

tensor: The alignment tensor identification string.





10.2.7 align_tensor.fix()

10.2.7.1 Synopsis

Fix all alignment tensors so that they do not change during optimisation.

10.2.7.2 Defaults

align_tensor.
[0]
[0]fix
(
[0]self, fixed=
[0]True)

10.2.7.3 Keyword Arguments

fixed: The flag specifying if the tensors should be fixed or variable.





10.2.8 align_tensor.init()

10.2.8.1 Synopsis

Function for initialising the alignment tensor.

10.2.8.2 Defaults

align_tensor.
[0]
[0]init
(
[0]self, tensor=
[0]None, params=
[0]None, scale=
[0]1.0, angle_units=
[0]`deg', param_types=
[0]0, errors=
[0]False)

10.2.8.3 Keyword Arguments

tensor: The alignment tensor identification string.

params: The alignment tensor data.

scale: The alignment tensor eigenvalue scaling value.

angle_units: The units for the angle parameters.

param_types: A flag to select different parameter combinations.

errors: A flag which determines if the alignment tensor data or its errors are being input.

10.2.8.4 Description

Using this function, the alignment tensor data can be set up. The params argument should be a tuple of floating point numbers (a list surrounded by round brakets). These correspond to the parameters of the tensor, which can be specified by the param_types argument, where the values correspond to

0 -
{Sxx, Syy, Sxy, Sxz, Syz} (unitless),
1 -
{Szz, Sxx-yy, Sxy, Sxz, Syz} (Pales default format),
2 -
{Axx, Ayy, Axy, Axz, Ayz} (unitless),
3 -
{Azz, Axx-yy, Axy, Axz, Ayz} (unitless),
4 -
{Axx, Ayy, Axy, Axz, Ayz} (units of Hertz),
5 -
{Azz, Axx-yy, Axy, Axz, Ayz} (units of Hertz),
6 -
{Pxx, Pyy, Pxy, Pxz, Pyz} (unitless),
7 -
{Pzz, Pxx-yy, Pxy, Pxz, Pyz} (unitless),

Other formats may be added later. The relationship between the Saupe order matrix S and the alignment tensor A is

S = 3/2 A.

The probability matrix P is related to the alignment tensor A by

A = P - 1/3 I,

where I is the identity matrix. For the alignment tensor to be supplied in Hertz, the bond vectors must all be of equal length.

10.2.8.5 Examples

To set a rhombic tensor to the run `CaM', type one of:


relax> align_tensor.
[0]
[0]
[0]init(
[0]
[0]`super media', (
[0]
[0]-8.6322e-05, -5.5786e-04, -3.1732e-05, 2.2927e-05, 2.8599e-04), param_types=
[0]
[0]1)


relax> align_tensor.
[0]
[0]
[0]init(
[0]
[0]tensor=
[0]
[0]`super media', params=
[0]
[0](
[0]
[0]-8.6322e-05, -5.5786e-04, -3.1732e-05, 2.2927e-05, 2.8599e-04), param_types=
[0]
[0]1)





10.2.9 align_tensor.matrix_angles()

10.2.9.1 Synopsis

Function for calculating the 5D angles between all alignment tensors.

10.2.9.2 Defaults

align_tensor.
[0]matrix_angles
(
[0]self, basis_set=
[0]0, tensors=
[0]None)

10.2.9.3 Keyword Arguments

basis_set: The basis set to operate with.

tensors: A list of the tensors to apply the calculation to. If None, all tensors are used.

10.2.9.4 Description

This function will calculate the angles between all loaded alignment tensors for the current data pipe. The matrices are first converted to a 5D vector form and then then angles are calculated. The angles are dependent on the basis set. If the basis_set argument is set to the default of 0, the vectors {Sxx, Syy, Sxy, Sxz, Syz} are used. If the basis_set argument is set to 1, the vectors {Szz, Sxxyy, Sxy, Sxz, Syz} are used instead.





10.2.10 align_tensor.reduction()

10.2.10.1 Synopsis

Specify that one tensor is a reduction of another.

10.2.10.2 Defaults

align_tensor.
[0]reduction
(
[0]self, full_tensor=
[0]None, red_tensor=
[0]None)

10.2.10.3 Keyword Arguments

full_tensor: The full alignment tensor.

red_tensor: The reduce alignment tensor.

10.2.10.4 Description

Prior to optimisation of the N-state model and Frame Order theories using alignment tensors, which tensor is a reduction of which other tensor must be specified through this user function.

10.2.10.5 Examples

To state that the alignment tensor loaded as `chi3 C-dom' is a reduction of `chi3 N-dom', type:


relax> align_tensor.
[0]
[0]reduction(
[0]
[0]full_tensor=
[0]
[0]`chi3 N-dom', red_tensor=
[0]
[0]`chi3 C-dom')





10.2.11 align_tensor.set_domain()

10.2.11.1 Synopsis

Set the domain label for the alignment tensor.

10.2.11.2 Defaults

align_tensor.
[0]set_domain
(
[0]self, tensor=
[0]None, domain=
[0]None)

10.2.11.3 Keyword Arguments

tensor: The alignment tensor to assign the domain label to.

domain: The domain label.

10.2.11.4 Description

Prior to optimisation of the N-state model or Frame Order theories, the domain to which each alignment tensor belongs must be specified.

10.2.11.5 Examples

To link the alignment tensor loaded as `chi3 C-dom' to the C-terminal domain `C', type:


relax> align_tensor.
[0]
[0]set_domain(
[0]
[0]tensor=
[0]
[0]`chi3 C-dom', domain=
[0]
[0]`C')





10.2.12 align_tensor.svd()

10.2.12.1 Synopsis

Function for calculating the singular values for all tensors and the condition number.

10.2.12.2 Defaults

align_tensor.
[0]svd
(
[0]self, basis_set=
[0]0, tensors=
[0]None)

10.2.12.3 Keyword Arguments

basis_set: The basis set to operate with.

tensors: A list of the tensors to apply the calculation to. If None, all tensors are used.

10.2.12.4 Description

This function will, using SVD, calculate the singular values of all tensors loaded for the current data pipe. If the basis_set argument is set to the default of 0, the matrix on which SVD will be performed is composed of the unitary basis set {Sxx, Syy, Sxy, Sxz, Syz} layed out as:

 
  
     | Sxx1 Syy1 Sxy1 Sxz1 Syz1 | 
     | Sxx2 Syy2 Sxy2 Sxz2 Syz2 | 
     | Sxx3 Syy3 Sxy3 Sxz3 Syz3 | 
     |  .    .    .    .    .   | 
     |  .    .    .    .    .   | 
     |  .    .    .    .    .   | 
     | SxxN SyyN SxyN SxzN SyzN |

If basis_set is set to 1, the geometric basis set consisting of the stretching and skewing parameters Szz and Sxx-yy respectively {Szz, Sxxyy, Sxy, Sxz, Syz} will be used instead. The matrix is:

 
  
     | Szz1 Sxxyy1 Sxy1 Sxz1 Syz1 | 
     | Szz2 Sxxyy2 Sxy2 Sxz2 Syz2 | 
     | Szz3 Sxxyy3 Sxy3 Sxz3 Syz3 | 
     |  .     .     .    .    .   | 
     |  .     .     .    .    .   | 
     |  .     .     .    .    .   | 
     | SzzN SxxyyN SxyN SxzN SyzN |

The relationships between the geometric and unitary basis sets are:

 
  
     Szz = - Sxx - Syy, 
     Sxxyy = Sxx - Syy,

The SVD values and condition number are dependendent upon the basis set chosen.






10.2.13 angle_diff_frame()

10.2.13.1 Synopsis

Calculate the angles defining the XH bond vector within the diffusion frame.

10.2.13.2 Defaults

angle_diff_frame(
[0]self)

10.2.13.3 Description

If the diffusion tensor is isotropic, then nothing will be done.

If the diffusion tensor is axially symmetric, then the angle $ \alpha$ will be calculated for each XH bond vector.

If the diffusion tensor is asymmetric, then the three angles will be calculated.





10.2.14 bmrb.citation()

10.2.14.1 Synopsis

Specify a citation to be added the BMRB data file.

10.2.14.2 Defaults

bmrb.
[0]
[0]citation
(
[0]self, cite_id=
[0]None, authors=
[0]None, doi=
[0]None, pubmed_id=
[0]None, full_citation=
[0]None, title=
[0]None, status=
[0]`published', type=
[0]`journal', journal_abbrev=
[0]None, journal_full=
[0]None, volume=
[0]None, issue=
[0]None, page_first=
[0]None, page_last=
[0]None, year=
[0]None)

10.2.14.3 Keyword Arguments

cite_id: The citation ID string.

authors: The list of authors. Each author element is a list of four elements (the first name, last name, first initial, and middle initials).

doi: The DOI number, e.g. "10.1000/182".

pubmed_id: The identification code assigned to the publication by PubMed.

full_citation: The full citation as given in a reference list.

title: The title of the publication.

status: The publication status.

journal_abbrev: The standard journal abbreviation.

journal_full: The full journal name.

volume: The volume number.

issue: The issue number.

page_first: The first page number.

page_last: The last page number.

year: The publication year.

10.2.14.4 Description

The full_citation should be in a format similar to that used in a journal article by either cutting and pasting from another document or by typing. Please include author names, title, journal, page numbers, and year or equivalent information for the type of publication given.

The journal status can only be one of:

"preparation",
"in press",
"published",
"retracted",
"submitted".

The citation type can only be one of:

"abstract",
"BMRB only",
"book",
"book chapter",
"internet",
"journal",
"personal communication",
"thesis".

The standard journal abbreviation is that defined by the Chemical Abstract Services for the journal where the data are or will be published. If the data in the deposition are related to a J. Biomol. NMR paper, the value must be `J. Biomol. NMR' to alert the BMRB annotators so that the deposition is properly processed. If the depositor truly does not know the journal, a value of `not known' or `na' is acceptable.

10.2.14.5 Examples

To add the citation "d'Auvergne E. J., Gooley P. $ \mathfrak{R}$ . (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494.", type:


relax> bmrb.
[0]
[0]
[0]citation(
[0]
[0]authors=
[0]
[0][["Edward", "d'Auvergne", "E.", "J."], ["Paul", "Gooley", "P.", "R."]], doi=
[0]
[0]"10.1039/b702202f", pubmed_id=
[0]
[0]"17579774", full_citation=
[0]
[0]"d'Auvergne E. J., Gooley P. R. (
[0]
[0]2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(
[0]
[0]7), 483-494.", title=
[0]
[0]"Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm.", status=
[0]
[0]"published", type=
[0]
[0]"journal", journal_abbrev=
[0]
[0]"Mol. Biosyst.", journal_full=
[0]
[0]"Molecular Biosystems", volume=
[0]
[0]3, issue=
[0]
[0]7, page_first=
[0]
[0]483, page_last=
[0]
[0]498, year=
[0]
[0]2007)





10.2.15 bmrb.display()

10.2.15.1 Synopsis

Display the BMRB data in NMR-STAR format.

10.2.15.2 Defaults

bmrb.
[0]
[0]display
(
[0]self, version=
[0]None)





10.2.16 bmrb.read()

10.2.16.1 Synopsis

Read BMRB files in the NMR-STAR format.

10.2.16.2 Defaults

bmrb.
[0]read
(
[0]self, file=
[0]None, dir=
[0]None, version=
[0]None, sample_conditions=
[0]None)

10.2.16.3 Keyword Arguments

file: The name of the BMRB STAR formatted file.

dir: The directory where the file is located.

version: For the reading to use the given NMR-STAR version.

sample_conditions: The sample conditions label in the NMR-STAR file to restrict loading to.

10.2.16.4 Description

To search for the results file in the current working directory, set dir to None. Note that only one sample condition can be read per relax data pipe. Therefore if sample_conditions is not given and multiple conditions exist in the NMR-STAR file, a RelaxError will be raised.





10.2.17 bmrb.script()

10.2.17.1 Synopsis

Specify the scripts used in the analysis.

10.2.17.2 Defaults

bmrb.
[0]script
(
[0]self, file=
[0]`reduced', dir=
[0]None, analysis_type=
[0]None, model_selection=
[0]None, engine=
[0]`relax', model_elim=
[0]False, universal_solution=
[0]False)

10.2.17.3 Keyword Arguments

file: The script file name.

dir: The directory name.

analysis_type: The type of analysis performed.

model_selection: The model selection technique used, if relevant.

engine: The software engine used in the analysis.

model_elim: A model-free specific flag specifying if model elimination was performed.

universal_solution: A model-free specific flag specifying if the universal solution was sought after.

10.2.17.4 Description

This user function allows scripts used in the analysis to be included in the BMRB deposition. The following addition information may need to be specified with the script.

The analysis_type must be set. Allowable values include all the data pipe types used in relax, ie:

`frame order' -
The Frame Order theories,
`jw' -
Reduced spectral density mapping,
`mf' -
Model-free analysis,
`N-state' -
N-state model of domain motions,
`noe' -
Steady state NOE calculation,
`relax_fit' -
Relaxation curve fitting,

The model_selection argument only needs to be set if the script selects between different mathematical models. This can be anything, but the following are recommended:

`AIC' -
Akaike's Information Criteria.
`AICc' -
Small sample size corrected AIC.
`BIC' -
Bayesian or Schwarz Information Criteria.
`Bootstrap' -
Bootstrap model selection.
`CV' -
Single-item-out cross-validation.
`Expect' -
The expected overall discrepancy (the true values of the parameters are
`Farrow' -
Old model-free method by Farrow et al., 1994.
`Palmer' -
Old model-free method by Mandel et al., 1995.
`Overall' -
The realised overall discrepancy (the true values of the parameters are

The engine is the software used in the calculation, optimisation, etc. This can be anything, but those recognised by relax (automatic program info, citations, etc. added) include:

`relax' -
hence relax was used for the full analysis.
`modelfree4' -
Art Palmer's Modelfree4 program was used for optimising the model-free
`dasha' -
The Dasha program was used for optimising the model-free parameter values.
`curvefit' -
Art Palmer's curvefit program was used to determine the R$ _1$ or R$ _2$ values.

The model_elim flag is model-free specific and should be set if the methods from "d'Auvergne, E. J. and Gooley, P. $ \mathfrak{R}$ . (2006). Model-free model elimination: A new step in the model-free dynamic analysis of NMR relaxation data. J. Biomol. NMR, 35(2), 117-135." were used. This should be set to True for the full_analysis.py script.

The universal_solution flag is model-free specific and should be set if the methods from "d'Auvergne E. J., Gooley P. $ \mathfrak{R}$ . (2007). Set theory formulation of the model-free problem and the diffusion seeded model-free paradigm. Mol. Biosyst., 3(7), 483-494." were used. This should be set to True for the full_analysis.py script.

10.2.17.5 Examples

For BMRB deposition, to specify that the full_analysis.py script was used, type one of:


relax> bmrb.
[0]
[0]script(
[0]
[0]`full_analysis.
[0]
[0]py', `model-free', `AIC', `relax', True, True)


relax> bmrb.
[0]
[0]script(
[0]
[0]file=
[0]
[0]`full_analysis.
[0]
[0]py', dir=
[0]
[0]None, analysis_type=
[0]
[0]`model-free', model_selection=
[0]
[0]`AIC', engine=
[0]
[0]`relax', model_elim=
[0]
[0]True, universal_solution=
[0]
[0]True)





10.2.18 bmrb.software()

10.2.18.1 Synopsis

Specify the software used in the analysis.

10.2.18.2 Defaults

bmrb.
[0]software
(
[0]self, name=
[0]None, version=
[0]None, url=
[0]None, vendor_name=
[0]None, cite_ids=
[0]None, tasks=
[0]None)

10.2.18.3 Keyword Arguments

name: The name of the software program utilised.

version: The version of the software, if applicable.

url: The web address of the software.

vendor_name: The name of the company or person behind the program.

cite_ids: A list of the citation ID numbers.

tasks: A list of all the tasks performed by the software.

10.2.18.4 Description

This user function allows the software used in the analysis to be specified in full detail.

For the tasks list, this should be a python list of strings (eg. [`spectral processing']). Although not restricted to these, the values suggested by the BMRB are:

`chemical shift assignment',
`chemical shift calculation',
`collection',
`data analysis',
`geometry optimization',
`peak picking',
`processing',
`refinement',
`structure solution'

10.2.18.5 Examples

For BMRB deposition, to say that Sparky was used in the analysis, type:


relax> cite_id =
[0]
[0]bmrb.
[0]
[0]
[0]citation(
[0]
[0]authors=
[0]
[0][[`Tom', `Goddard', `T.', `D.'], [`D', `Kneller', `D.', `G.']], title=
[0]
[0]""Goddard, T. D. and Kneller, D. G., SPARKY 3, University of California, San Francisco."


relax> bmrb.
[0]
[0]software(
[0]
[0]`Sparky', version=
[0]
[0]`3.110', url=
[0]
[0]"http://www.
[0]
[0]
[0]cgl.
[0]
[0]ucsf.
[0]
[0]
[0]edu/home/sparky/", vendor_name=
[0]
[0]"Goddard, T. D.", cite_ids=
[0]
[0][cite_id], tasks=
[0]
[0]["spectral analysis"])





10.2.19 bmrb.software_select()

10.2.19.1 Synopsis

Select the software used in the analysis.

10.2.19.2 Defaults

bmrb.
[0]software_select
(
[0]self, name=
[0]None, version=
[0]None)

10.2.19.3 Keyword Arguments

name: The name of the software program utilised.

version: The version of the software, if applicable.

10.2.19.4 Description

Rather than specifying all the information directly, this user function allows the software packaged used in the analysis to be selected by name. The programs currently supported are:

`NMRPipe' - http -
//spin.niddk.nih.gov/NMRPipe/
`Sparky' - http -
//www.cgl.ucsf.edu/home/sparky/

More can be added if all relevant information (program name, description, website, original citation, purpose, etc.) is emailed to relax-users@gna.org.

Note that relax is automatically added to the BMRB file.

10.2.19.5 Examples

For BMRB deposition, to say that both NMRPipe and Sparky were used prior to relax, type:


relax> bmrb.
[0]
[0]software_select(
[0]
[0]`NMRPipe')


relax> bmrb.
[0]
[0]software_select(
[0]
[0]`Sparky', version=
[0]
[0]`3.113')





10.2.20 bmrb.thiol_state()

10.2.20.1 Synopsis

Select the thiol state of the system.

10.2.20.2 Defaults

bmrb.
[0]thiol_state
(
[0]self, state=
[0]`reduced')

10.2.20.3 Keyword Arguments

state: The thiol state.

10.2.20.4 Description

The thiol state can be any text, thought the BMRB suggests the following:

`all disulfide bound',
`all free',
`all other bound',
`disulfide and other bound',
`free and disulfide bound',
`free and other bound',
`free disulfide and other bound',
`not available',
`not present',
`not reported',
`unknown'.

Alternatively the pure states `reduced' or `oxidised' could be specified.

10.2.20.5 Examples

For BMRB deposition, to say that the protein studied is in the oxidised state, tyype one of:


relax> bmrb.
[0]
[0]thiol_state(
[0]
[0]`oxidised')


relax> bmrb.
[0]
[0]thiol_state(
[0]
[0]state=
[0]
[0]`oxidised')





10.2.21 bmrb.write()

10.2.21.1 Synopsis

Write the results to a BMRB NMR-STAR formatted file.

10.2.21.2 Defaults

bmrb.
[0]write
(
[0]self, file=
[0]None, dir=
[0]`pipe_name', version=
[0]None, force=
[0]False)

Keyword Arguments ~~~~~~~~~~~~~~~~~
file: The name of the BMRB file to output results to. Optionally this can be a file object, or any object with a write() method.
dir: The directory name.
version: The NMR-STAR dictionary format version to use.

.sconsign.dblite

force -
A flag which if True will cause the any pre-existing file to be overwritten.

Description ~~~~~~~~~~~
To place the BMRB file in the current working directory, set dir to None. If dir is set to the special name `pipe_name', then the results file will be placed into a directory with the same name as the current data pipe.





10.2.22 calc()

10.2.22.1 Synopsis

Function for calculating the function value.

10.2.22.2 Defaults

calc(
[0]self, verbosity=
[0]1)

10.2.22.3 Keyword Arguments

verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.





10.2.23 consistency_tests.set_frq()

10.2.23.1 Synopsis

Function for selecting which relaxation data to use in the consistency tests.

10.2.23.2 Defaults

consistency_tests.
[0]set_frq
(
[0]self, frq=
[0]None)

10.2.23.3 Keyword Arguments

frq: The spectrometer frequency in Hz.

10.2.23.4 Description

This function will select the relaxation data to use in the consistency tests corresponding to the given frequencies.

10.2.23.5 Examples


relax> consistency_tests.
[0]
[0]set_frq(
[0]
[0]600.0 * 1e6)


relax> consistency_tests.
[0]
[0]set_frq(
[0]
[0]frq=
[0]
[0]600.0 * 1e6)






10.2.24 dasha.create()

10.2.24.1 Synopsis

Function for creating the Dasha script.

10.2.24.2 Defaults

dasha.
[0]
[0]create
(
[0]self, algor=
[0]`LM', dir=
[0]None, force=
[0]False)

10.2.24.3 Keyword Arguments

algor: The minimisation algorithm.

dir: The directory to place the files.

force: A flag which if set to True will cause the results file to be overwritten if it already exists.

10.2.24.4 Description

The script file created is called `dir/dasha_script'.

10.2.24.5 Optimisation algorithms

The two minimisation algorithms within Dasha are accessible through the algor argument which can be set to:

`LM' - The Levenberg-Marquardt algorithm.
`NR' - Newton-Raphson algorithm.

For Levenberg-Marquardt minimisation, the function `lmin' will be called, while for Newton -Raphson, the function `min' will be executed.






10.2.25 dasha.execute()

10.2.25.1 Synopsis

Function for executing Dasha.

10.2.25.2 Defaults

dasha.
[0]
[0]execute
(
[0]self, dir=
[0]None, force=
[0]False, binary=
[0]`dasha')

10.2.25.3 Keyword Arguments

dir: The directory to place the files.

force: A flag which if set to True will cause the results file to be overwritten if it already exists.

binary: The name of the executable Dasha program file.

10.2.25.4 Execution

Dasha will be executed as


$ dasha < dasha_script | tee dasha_results

If you would like to use a different Dasha executable file, change the keyword argument `binary' to the appropriate file name. If the file is not located within the environment's path, include the full path in front of the binary file name.






10.2.26 dasha.extract()

10.2.26.1 Synopsis

Function for extracting data from the Dasha results file.

10.2.26.2 Defaults

dasha.
[0]
[0]extract
(
[0]self, dir=
[0]None)

10.2.26.3 Keyword Arguments

dir: The directory where the file `dasha_results' is found.





10.2.27 deselect.all()

10.2.27.1 Synopsis

Function for deselecting all spins.

10.2.27.2 Defaults

deselect.
[0]
[0]all
(
[0]self)

10.2.27.3 Examples

To deselect all spins, simply type:


relax> deselect.
[0]
[0]
[0]all(
[0]
[0])





10.2.28 deselect.read()

10.2.28.1 Synopsis

Function for deselecting the spins contained in a file.

10.2.28.2 Defaults

deselect.
[0]read
(
[0]self, file=
[0]None, dir=
[0]None, spin_id_col=
[0]None, mol_name_col=
[0]None, res_num_col=
[0]None, res_name_col=
[0]None, spin_num_col=
[0]None, spin_name_col=
[0]None, sep=
[0]None, spin_id=
[0]None, boolean=
[0]`AND', change_all=
[0]False)

10.2.28.3 Keyword Arguments

file: The name of the file containing the list of spins to deselect.

dir: The directory where the file is located.

spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).

mol_name_col: The molecule name column (alternative to the spin_id_col).

res_num_col: The residue number column (alternative to the spin_id_col).

res_name_col: The residue name column (alternative to the spin_id_col).

spin_num_col: The spin number column (alternative to the spin_id_col).

spin_name_col: The spin name column (alternative to the spin_id_col).

data_col: The RDC data column.

error_col: The experimental error column.

sep: The column separator (the default is white space).

spin_id: The spin ID string to restrict the loading of data to certain spin subsets.

boolean: The boolean operator specifying how spins should be selected.

change_all: A flag specifying if all other spins should be changed.

10.2.28.4 Description

The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.

Empty lines and lines beginning with a hash are ignored.

The `change_all' flag argument default is False meaning that all spins currently either selected or deselected will remain that way. Setting the argument to True will cause all spins not specified in the file to be selected.

10.2.28.5 Examples

To deselect all overlapped residues listed with residue numbers in the first column of the file `unresolved', type:


relax> deselect.
[0]
[0]read(
[0]
[0]`unresolved', res_num_col=
[0]
[0]1)


relax> deselect.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`unresolved', res_num_col=
[0]
[0]1)

To deselect the spins in the second column of the relaxation data file `r1.600' while selecting all other spins, for example type:


relax> deselect.
[0]
[0]read(
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)


relax> deselect.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)





10.2.29 deselect.reverse()

10.2.29.1 Synopsis

Function for the reversal of the spin selection.

10.2.29.2 Defaults

deselect.
[0]reverse
(
[0]self, spin_id=
[0]None)

10.2.29.3 Keyword Arguments

spin_id: The spin identification string.

10.2.29.4 Description

By supplying the spin_id argument, a subset of spin can have their selection status reversed.

10.2.29.5 Examples

To deselect all currently selected spins and select those which are deselected type:


relax> deselect.
[0]
[0]reverse(
[0]
[0])





10.2.30 deselect.spin()

10.2.30.1 Synopsis

Function for deselecting specific spins.

10.2.30.2 Defaults

deselect.
[0]spin
(
[0]self, spin_id=
[0]None, change_all=
[0]False)

10.2.30.3 Keyword Arguments

spin_id: The spin identification string.

change_all: A flag specifying if all other spins should be changed.

10.2.30.4 Description

The `change_all' flag argument default is False meaning that all spins currently either selected or deselected will remain that way. Setting the argument to True will cause all spins not specified by `spin_id' to be selected.

10.2.30.5 Examples

To deselect all glycines and alanines, type:


relax> deselect.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:GLY|:ALA')

To deselect residue 12 MET type:


relax> deselect.
[0]
[0]spin(
[0]
[0]`:12')


relax> deselect.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:12')


relax> deselect.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:12&:MET')





10.2.31 diffusion_tensor.copy()

10.2.31.1 Synopsis

Function for copying diffusion tensor data from one data pipe to another.

10.2.31.2 Defaults

diffusion_tensor.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, pipe_to=
[0]None)

10.2.31.3 Keyword Arguments

pipe_from: The name of the data pipe to copy the diffusion tensor data from.

pipe_to: The name of the data pipe to copy the diffusion tensor data to.

10.2.31.4 Description

This function will copy the diffusion tensor data between data pipes. The destination data pipe must not contain any diffusion tensor data. If the pipe_from or pipe_to arguments are not supplied, then both will default to the current data pipe (hence giving one argument is essential).

10.2.31.5 Examples

To copy the diffusion tensor from the data pipe `m1' to the current data pipe, type:


relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]`m1')


relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1')

To copy the diffusion tensor from the current data pipe to the data pipe `m9', type:


relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]pipe_to=
[0]
[0]`m9')

To copy the diffusion tensor from the data pipe `m1' to `m2', type:


relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2')


relax> diffusion_tensor.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m2')





10.2.32 diffusion_tensor.delete()

10.2.32.1 Synopsis

Function for deleting diffusion tensor data.

10.2.32.2 Defaults

diffusion_tensor.
[0]
[0]delete
(
[0]self)

10.2.32.3 Description

This function will delete all diffusion tensor data from the current data pipe.





10.2.33 diffusion_tensor.display()

10.2.33.1 Synopsis

Function for displaying the diffusion tensor information.

10.2.33.2 Defaults

diffusion_tensor.
[0]
[0]display
(
[0]self)





10.2.34 diffusion_tensor.init()

10.2.34.1 Synopsis

Function for initialising the diffusion tensor.

10.2.34.2 Defaults

diffusion_tensor.
[0]
[0]init
(
[0]self, params=
[0]None, time_scale=
[0]1.0, d_scale=
[0]1.0, angle_units=
[0]`deg', param_types=
[0]0, spheroid_type=
[0]None, fixed=
[0]True)

10.2.34.3 Keyword Arguments

params: The diffusion tensor data.

time_scale: The correlation time scaling value.

d_scale: The diffusion tensor eigenvalue scaling value.

angle_units: The units for the angle parameters.

param_types: A flag to select different parameter combinations.

spheroid_type: A string which, if supplied together with spheroid parameters, will restrict the tensor to either being `oblate' or `prolate'.

fixed: A flag specifying whether the diffusion tensor is fixed or can be optimised.


10.2.34.4 The sphere (isotropic diffusion)

When the molecule diffuses as a sphere, all three eigenvalues of the diffusion tensor are equal, $ \mathfrak{D}_x$ = $ \mathfrak{D}_y$ = $ \mathfrak{D}_z$ . In this case, the orientation of the XH bond vector within the diffusion frame is inconsequential to relaxation, hence, the spherical or Euler angles are undefined. Therefore solely a single geometric parameter, either $ \tau _m$ or $ \mathfrak{D}_{iso}$ , can fully and sufficiently parameterise the diffusion tensor. The correlation function for the global rotational diffusion is

 
              1   - tau / tm 
     C(tau) = - e            , 
              5

To select isotropic diffusion, the parameters argument should be a single floating point number. The number is the value of the isotropic global correlation time, $ \tau _m$ , in seconds. To specify the time in nanoseconds, set the `time_scale' argument to 1e-9. Alternative parameters can be used by changing the `param_types' flag to the following integers

0 -
{tm} (Default),
1 -
{Diso},

where

1 / $ \tau _m$ = 6 $ \mathfrak{D}_{iso}$ .


10.2.34.5 The spheroid (axially symmetric diffusion)

When two of the three eigenvalues of the diffusion tensor are equal, the molecule diffuses as a spheroid. Four pieces of information are required to specify this tensor, the two geometric parameters, $ \mathfrak{D}_{iso}$ and $ \mathfrak{D}_a$ , and the two orientational parameters, the polar angle $ \theta$ and the azimuthal angle $ \phi$ describing the orientation of the axis of symmetry. The correlation function of the global diffusion is

 
                _1_ 
              1 \          - tau / tau_i 
     C(tau) = -  >  ci . e              , 
              5 /__ 
                i=-1

where

c-1 = 1/4 (3 $ \delta_z$ ^2 - 1)^2,
c0 = 3 $ \delta_z$ ^2 (1 - $ \delta_z$ ^2),
c1 = 3/4 ($ \delta_z$ ^2 - 1)^2,

and

1 / $ \tau$ -1 = 6 $ \mathfrak{D}_{iso}$ - 2 $ \mathfrak{D}_a$ ,
1 / $ \tau$ 0 = 6 $ \mathfrak{D}_{iso}$ - $ \mathfrak{D}_a$ ,
1 / $ \tau$ 1 = 6 $ \mathfrak{D}_{iso}$ + 2 $ \mathfrak{D}_a$ .

The direction cosine $ \delta_z$ is defined as the cosine of the angle $ \alpha$ between the XH bond vector and the unique axis of the diffusion tensor.

To select axially symmetric anisotropic diffusion, the parameters argument should be a tuple of floating point numbers of length four. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, `param_types', are

0 -
{$ \tau _m$ , $ \mathfrak{D}_a$ , $ \theta$ , $ \phi$ } (Default),
1 -
{ $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_a$ , $ \theta$ , $ \phi$ },
2 -
{$ \tau _m$ , $ \mathfrak{D}_{ratio}$ , $ \theta$ , $ \phi$ },
3 -
{ $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ , $ \mathfrak{D}_{\scriptscriptstyle \perp}$ , $ \theta$ , $ \phi$ },
4 -
{ $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_{ratio}$ , $ \theta$ , $ \phi$ },

where

$ \tau _m$ = 1 / 6 $ \mathfrak{D}_{iso}$ ,
$ \mathfrak{D}_{iso}$ = 1/3 ( $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ + 2 $ \mathfrak{D}_{\scriptscriptstyle \perp}$ ),
$ \mathfrak{D}_a$ = $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ - $ \mathfrak{D}_{\scriptscriptstyle \perp}$ ,
$ \mathfrak{D}_{ratio}$ = $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ / $ \mathfrak{D}_{\scriptscriptstyle \perp}$ .

The spherical angles {$ \theta$ , $ \phi$ } orienting the unique axis of the diffusion tensor within the PDB frame are defined between

0 $ \le$ $ \theta$ $ \le$ $ \pi$ ,
0 $ \le$ $ \phi$ $ \le$ 2$ \pi$ ,

while the angle $ \alpha$ which is the angle between this axis and the given XH bond vector is defined between

0 $ \le$ $ \alpha$ $ \le$ 2$ \pi$ .

The `spheroid_type' argument should be `oblate', `prolate', or None. The argument will be ignored if the diffusion tensor is not axially symmetric. If `oblate' is given, then the constraint $ \mathfrak{D}_a$ $ \le$ 0 is used while if `prolate' is given, then the constraint $ \mathfrak{D}_a$ $ \ge$ 0 is used. If nothing is supplied, then $ \mathfrak{D}_a$ will be allowed to have any values. To prevent minimisation of diffusion tensor parameters in a space with two minima, it is recommended to specify which tensor is to be minimised, thereby partitioning the two minima into the two subspaces along the boundry $ \mathfrak{D}_a$ = 0.


10.2.34.6 The ellipsoid (rhombic diffusion)

When all three eigenvalues of the diffusion tensor are different, the molecule diffuses as an ellipsoid. This diffusion is also known as fully anisotropic, asymmetric, or rhombic. The full tensor is specified by six pieces of information, the three geometric parameters $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_a$ , and $ \mathfrak{D}_r$ representing the isotropic, anisotropic, and rhombic components of the tensor, and the three Euler angles $ \alpha$ , $ \beta$ , and $ \gamma$ orienting the tensor within the PDB frame. The correlation function is

 
                _2_ 
              1 \          - tau / tau_i 
     C(tau) = -  >  ci . e              , 
              5 /__ 
                i=-2

where the weights on the exponentials are

c-2 = 1/4 (d + e),
c-1 = 3 $ \delta_y$ ^2 $ \delta_z$ ^2,
c0 = 3 $ \delta_x$ ^2 $ \delta_z$ ^2,
c1 = 3 $ \delta_x$ ^2 $ \delta_y$ ^2,
c2 = 1/4 (d + e).

Let

$ \mathfrak{R}$ = sqrt(1 + 3 $ \mathfrak{D}_r$ ),

then

d = 3 ($ \delta_x$ ^4 + $ \delta_y$ ^4 + $ \delta_z$ ^4) - 1,
e = - 1 / $ \mathfrak{R}$ ((1 + 3 $ \mathfrak{D}_r$ )($ \delta_x$ ^4 + 2$ \delta_y$ ^2 $ \delta_z$ ^2) + (1 - 3 $ \mathfrak{D}_r$ )($ \delta_y$ ^4 + 2$ \delta_x$ ^2 $ \delta_z$ ^2) - 2($ \delta_z$ ^4 + 2$ \delta_x$ ^2 $ \delta_y$ ^2)).

The correlation times are

1 / $ \tau$ -2 = 6 $ \mathfrak{D}_{iso}$ - 2 $ \mathfrak{D}_a$ . $ \mathfrak{R}$ ,
1 / $ \tau$ -1 = 6 $ \mathfrak{D}_{iso}$ - $ \mathfrak{D}_a$ (1 + 3 $ \mathfrak{D}_r$ ),
1 / $ \tau$ 0 = 6 $ \mathfrak{D}_{iso}$ - $ \mathfrak{D}_a$ (1 - 3 $ \mathfrak{D}_r$ ),
1 / $ \tau$ 1 = 6 $ \mathfrak{D}_{iso}$ + 2 $ \mathfrak{D}_a$ ,
1 / $ \tau$ 1 = 6 $ \mathfrak{D}_{iso}$ + 2 $ \mathfrak{D}_a$ . $ \mathfrak{R}$ .

The three direction cosines $ \delta_x$ , $ \delta_y$ , and $ \delta_z$ are the coordinates of a unit vector parallel to the XH bond vector. Hence the unit vector is [$ \delta_x$ , $ \delta_y$ , $ \delta_z$ ].

To select fully anisotropic diffusion, the parameters argument should be a tuple of length six. A tuple is a type of data structure enclosed in round brackets, the elements of which are separated by commas. Alternative sets of parameters, `param_types', are

0 -
{$ \tau _m$ , $ \mathfrak{D}_a$ , $ \mathfrak{D}_r$ , $ \alpha$ , $ \beta$ , $ \gamma$ } (Default),
1 -
{ $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_a$ , $ \mathfrak{D}_r$ , $ \alpha$ , $ \beta$ , $ \gamma$ },
2 -
{ $ \mathfrak{D}_x$ , $ \mathfrak{D}_y$ , $ \mathfrak{D}_z$ , $ \alpha$ , $ \beta$ , $ \gamma$ },
3 -
{Dxx, Dyy, Dzz, Dxy, Dxz, Dyz},

where

$ \tau _m$ = 1 / 6 $ \mathfrak{D}_{iso}$ ,
$ \mathfrak{D}_{iso}$ = 1/3 ( $ \mathfrak{D}_x$ + $ \mathfrak{D}_y$ + $ \mathfrak{D}_z$ ),
$ \mathfrak{D}_a$ = $ \mathfrak{D}_z$ - ( $ \mathfrak{D}_x$ + $ \mathfrak{D}_y$ )/2,
$ \mathfrak{D}_r$ = ( $ \mathfrak{D}_y$ - $ \mathfrak{D}_x$ )/2 $ \mathfrak{D}_a$ .

The angles $ \alpha$ , $ \beta$ , and $ \gamma$ are the Euler angles describing the diffusion tensor within the PDB frame. These angles are defined using the z-y-z axis rotation notation where $ \alpha$ is the initial rotation angle around the z-axis, $ \beta$ is the rotation angle around the y-axis, and $ \gamma$ is the final rotation around the z-axis again. The angles are defined between

0 $ \le$ $ \alpha$ $ \le$ 2$ \pi$ ,
0 $ \le$ $ \beta$ $ \le$ $ \pi$ ,
0 $ \le$ $ \gamma$ $ \le$ 2$ \pi$ .

Within the PDB frame, the XH bond vector is described using the spherical angles $ \theta$ and $ \phi$ where $ \theta$ is the polar angle and $ \phi$ is the azimuthal angle defined between

0 $ \le$ $ \theta$ $ \le$ $ \pi$ ,
0 $ \le$ $ \phi$ $ \le$ 2$ \pi$ .

When param_types is set to 3, then the elements of the diffusion tensor matrix defined within the PDB frame can be supplied.

10.2.34.7 Units

The `time_scale' argument should be a floating point number. The only parameter affected by this value is $ \tau _m$ .

The `d_scale' argument should also be a floating point number. Parameters affected by this value are $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ , $ \mathfrak{D}_{\scriptscriptstyle \perp}$ , $ \mathfrak{D}_a$ , $ \mathfrak{D}_x$ , $ \mathfrak{D}_y$ , and $ \mathfrak{D}_z$ . Significantly, $ \mathfrak{D}_r$ is not affected.

The `angle_units' argument should either be the string `deg' or `rad'. Parameters affected are $ \theta$ , $ \phi$ , $ \alpha$ , $ \beta$ , and $ \gamma$ .

10.2.34.8 Examples

To set an isotropic diffusion tensor with a correlation time of 10 ns, type:


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]10e-9)


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0]10e-9)


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]10.0, 1e-9)


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0]10.0, time_scale=
[0]
[0]1e-9, fixed=
[0]
[0]True)

To select axially symmetric diffusion with a $ \tau _m$ value of 8.5 ns, $ \mathfrak{D}_{ratio}$ of 1.1, $ \theta$ value of 20 degrees, and $ \phi$ value of 20 degrees, type:


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]8.5e-9, 1.1, 20.0, 20.0), param_types=
[0]
[0]2)

To select a spheroid diffusion tensor with a $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ value of 1.698e7, $ \mathfrak{D}_{\scriptscriptstyle \perp}$ value of 1.417e7, $ \theta$ value of 67.174 degrees, and $ \phi$ value of -83.718 degrees, type one of:


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.698e7, 1.417e7, 67.174, -83.718), param_types=
[0]
[0]3)


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0](
[0]
[0]1.698e7, 1.417e7, 67.174, -83.718), param_types=
[0]
[0]3)


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 67.174, -83.718), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8)


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 67.174, -83.718), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8)


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8, angle_units=
[0]
[0]`rad')


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0]params=
[0]
[0](
[0]
[0]1.698e-1, 1.417e-1, 1.1724, -1.4612), param_types=
[0]
[0]3, d_scale=
[0]
[0]1e8, angle_units=
[0]
[0]`rad', fixed=
[0]
[0]True)

To select ellipsoidal diffusion, type:


relax> diffusion_tensor.
[0]
[0]
[0]init(
[0]
[0](
[0]
[0]1.340e7, 1.516e7, 1.691e7, -82.027, -80.573, 65.568), param_types=
[0]
[0]2)





10.2.35 dx.execute()

10.2.35.1 Synopsis

Function for running OpenDX.

10.2.35.2 Defaults

dx.
[0]
[0]execute
(
[0]self, file=
[0]`map', dir=
[0]`dx', dx_exe=
[0]`dx', vp_exec=
[0]True)

10.2.35.3 Keyword Arguments

file: The file name prefix. For example if file is set to `temp', then the OpenDX program temp.net will be loaded.

dir: The directory to change to for running OpenDX. If this is set to None, OpenDX will be run in the current directory.

$ \delta_x$ _exe: The OpenDX executable file.

vp_exec: A flag specifying whether to execute the visual program automatically at start-up. The default of True causes the program to be executed.





10.2.36 dx.map()

10.2.36.1 Synopsis

Function for creating a map of the given space in OpenDX format.

10.2.36.2 Defaults

dx.
[0]map
(
[0]self, params=
[0]None, map_type=
[0]`Iso3D', spin_id=
[0]None, inc=
[0]20, lower=
[0]None, upper=
[0]None, axis_incs=
[0]5, file_prefix=
[0]`map', dir=
[0]`dx', point=
[0]None, point_file=
[0]`point', remap=
[0]None)

10.2.36.3 Keyword Arguments

params: The parameters to be mapped. This argument should be an array of strings, the meanings of which are described below.

map_type: The type of map to create. For example the default, a 3D isosurface, the type is `Iso3D'. See below for more details.

spin_id: The spin identification numbe.

inc: The number of increments to map in each dimension. This value controls the resolution of the map.

lower: The lower bounds of the space. If you wish to change the lower bounds of the map then supply an array of length equal to the number of parameters in the model. A lower bound for each parameter must be supplied. If nothing is supplied then the defaults will be used.

upper: The upper bounds of the space. If you wish to change the upper bounds of the map then supply an array of length equal to the number of parameters in the model. A upper bound for each parameter must be supplied. If nothing is supplied then the defaults will be used.

axis_incs: The number of increments or ticks displaying parameter values along the axes of the OpenDX plot.

file_prefix: The file name. All the output files are prefixed with this name. The main file containing the data points will be called the value of `file'. The OpenDX program will be called `file.net' and the OpenDX import file will be called `file.general'.

dir: The directory to output files to. Set this to `None' if you do not want the files to be placed in subdirectory. If the directory does not exist, it will be created.

point: An array of parameter values where a point in the map, shown as a red sphere, will be placed. The length must be equal to the number of parameters.

point_file: The name of that the point output files will be prefixed with.

remap: A user supplied remapping function. This function will receive the parameter array and must return an array of equal length.


10.2.36.4 Map type

The map type can be changed by supplying the `map_type' keyword argument. Here is a list of currently supported map types:

(see table 10.1)

Table: First table for the dx.map() user function.
Surface type Pattern
3D isosurface `Iso3D'

This argument is case insensitive.

10.2.36.5 Examples

The following commands will generate a map of the extended model-free space for model `m5' consisting of the parameters {$ S^2$ , $ S^2_f$ , $ \tau _s$ }. Files will be output into the directory `dx' and will be prefixed by `map'. In this case, the system is a protein and residue number 6 will be mapped.


relax> dx.
[0]
[0]map(
[0]
[0][`S2', `S2f', `ts'], spin_id=
[0]
[0]`:6')


relax> dx.
[0]
[0]map(
[0]
[0][`S2', `S2f', `ts'], spin_id=
[0]
[0]`:6', file_prefix=
[0]
[0]`map', dir=
[0]
[0]`dx')


relax> dx.
[0]
[0]map(
[0]
[0]params=
[0]
[0][`S2', `S2f', `ts'], spin_id=
[0]
[0]`:6', inc=
[0]
[0]20, file_prefix=
[0]
[0]`map', dir=
[0]
[0]`dx')


relax> dx.
[0]
[0]map(
[0]
[0]params=
[0]
[0][`S2', `S2f', `ts'], spin_id=
[0]
[0]`:6', map_type=
[0]
[0]`Iso3D', inc=
[0]
[0]20, file_prefix=
[0]
[0]`map', dir=
[0]
[0]`dx')

To map the model-free space `m4' for residue 2, spin N6 defined by the parameters {$ S^2$ , $ \tau _e$ , $ R_{ex}$ }, name the results `test', and to place the files in the current directory, use one of the following commands:


relax> dx.
[0]
[0]map(
[0]
[0][`S2', `te', `Rex'], spin_id=
[0]
[0]`:2@N6', file_prefix=
[0]
[0]`test', dir=
[0]
[0]None)


relax> dx.
[0]
[0]map(
[0]
[0]params=
[0]
[0][`S2', `te', `Rex'], spin_id=
[0]
[0]`:2@N6', inc=
[0]
[0]100, file_prefix=
[0]
[0]`test', dir=
[0]
[0]None)


10.2.36.6 Regular expression

The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.

This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:

`[]' -
A sequence or set of characters to match to a single character. For example, `[Ss]2' will match both `S2' and `s2'.
`^' -
Match the start of the string.
`$' -
Match the end of the string. For example, `^[Ss]2$' will match `s2' but not `S2f' or `s2s'.
`.' -
Match any character.
`x*' -
Match the character `x' any number of times, for example `x' will match, as will `xxxxx'
`.*' -
Match any sequence of characters of any length.

Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.


10.2.36.7 Diffusion tensor parameter string matching patterns

(see table 10.2)

Table: Second table for the dx.map() user function.
Data type Object name Patterns
Global correlation time - $ \tau _m$ `tm' `^tm$'
Isotropic component of the diffusion tensor - $ \mathfrak{D}_{iso}$ `Diso' `[Dd]iso'
Anisotropic component of the diffusion tensor - $ \mathfrak{D}_a$ `Da' `[Dd]a'
Rhombic component of the diffusion tensor - $ \mathfrak{D}_r$ `Dr' `[Dd]r$'
Eigenvalue associated with the x-axis of the diffusion `Dx' `[Dd]x'
diffusion tensor - $ \mathfrak{D}_x$
Eigenvalue associated with the y-axis of the diffusion `Dy' `[Dd]y'
diffusion tensor - $ \mathfrak{D}_y$
Eigenvalue associated with the z-axis of the diffusion `Dz' `[Dd]z'
diffusion tensor - $ \mathfrak{D}_z$
Diffusion coefficient parallel to the major axis of `Dpar' `[Dd]par'
the spheroid diffusion tensor - $ \mathfrak{D}_{\scriptscriptstyle \parallel}$
Diffusion coefficient perpendicular to the major axis `Dper' `[Dd]per'
of the spheroid diffusion tensor - $ \mathfrak{D}_{\scriptscriptstyle \perp}$
Ratio of the parallel and perpendicular components of `Dratio' `[Dd]ratio'
the spheroid diffusion tensor - $ \mathfrak{D}_{ratio}$
The first Euler angle of the ellipsoid diffusion `alpha' `^a$' or `alpha'
tensor - $ \alpha$
The second Euler angle of the ellipsoid diffusion `beta' `^b$' or `beta'
tensor - $ \beta$
The third Euler angle of the ellipsoid diffusion `gamma' `^g$' or `gamma'
tensor - $ \gamma$
The polar angle defining the major axis of the `theta' `theta'
spheroid diffusion tensor - $ \theta$
The azimuthal angle defining the major axis of the `phi' `phi'
spheroid diffusion tensor - $ \phi$

10.2.36.8 Model-free data type string matching patterns

(see table 10.3)

Table: Third table for the dx.map() user function.
Data type Object name Patterns
Local $ \tau _m$ `local_tm' `[Ll]ocal[ -_]tm'
Order parameter $ S^2$ `s2' `^[Ss]2$'
Order parameter $ S^2_f$ `s2f' `^[Ss]2f$'
Order parameter $ S^2_s$ `s2s' `^[Ss]2s$'
Correlation time $ \tau _e$ `te' `^te$'
Correlation time $ \tau _f$ `tf' `^tf$'
Correlation time $ \tau _s$ `ts' `^ts$'
Chemical exchange `rex' `^[Rr]ex$' or `[Cc]emical[ -_][Ee]xchange'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'





10.2.37 eliminate()

10.2.37.1 Synopsis

Function for model elimination.

10.2.37.2 Defaults

eliminate(
[0]self, function=
[0]None, args=
[0]None)

10.2.37.3 Keyword arguments

function: A user supplied function for model elimination.

args: A tuple of arguments for model elimination.

10.2.37.4 Description

This function is used for model validation to eliminate or reject models prior to model selection. Model validation is a part of mathematical modelling whereby models are either accepted or rejected.

Empirical rules are used for model rejection and are listed below. However these can be overridden by supplying a function. The function should accept five arguments, a string defining a certain parameter, the value of the parameter, the minimisation instance (ie the residue index if the model is residue specific), and the function arguments. If the model is rejected, the function should return True, otherwise it should return False. The function will be executed multiple times, once for each parameter of the model.

The `args' keyword argument should be a tuple, a list enclosed in round brackets, and will be passed to the user supplied function or the inbuilt function. For a description of the arguments accepted by the inbuilt functions, see below.

Once a model is rejected, the select flag corresponding to that model will be set to False so that model selection, or any other function, will then skip the model.


10.2.37.5 Local $ \tau _m$ model elimination rule

The local $ \tau _m$ , in some cases, may exceed the value expected for a global correlation time. Generally the $ \tau _m$ value will be stuck at the upper limit defined for the parameter. These models are eliminated using the rule:

$ \tau _m$ $ \ge$ c

The default value of c is 50 ns, although this can be overridden by supplying the value (in seconds) as the first element of the args tuple.


10.2.37.6 Internal correlation times {$ \tau _e$ , $ \tau _f$ , $ \tau _s$ } model elimination rules

These parameters may experience the same problem as the local $ \tau _m$ in that the model fails and the parameter value is stuck at the upper limit. These parameters are constrained using the formula ($ \tau _e$ , $ \tau _f$ , $ \tau _s$ $ \le$ 2$ \tau _m$ ). These failed models are eliminated using the rule:

$ \tau _e$ , $ \tau _f$ , $ \tau _s$ $ \ge$ c . $ \tau _m$

The default value of c is 1.5. Because of round-off errors and the constraint algorithm, setting c to 2 will result in no models being eliminated as the minimised parameters will always be less than 2$ \tau _m$ . The value can be changed by supplying the value as the second element of the tuple.

10.2.37.7 Arguments

The `args' argument must be a tuple of length 2, the elements of which must be numbers. For example, to eliminate models which have a local $ \tau _m$ value greater than 25 ns and models with internal correlation times greater than 1.5 times $ \tau _m$ , set `args' to (25 * 1e-9, 1.5).





10.2.38 fix()

10.2.38.1 Synopsis

Function for either fixing or allowing parameter values to change during optimisation.

10.2.38.2 Defaults

fix(
[0]self, element=
[0]None, fixed=
[0]True)

10.2.38.3 Keyword Arguments

element: Which element to fix.

fixed: A flag specifying if the parameters should be fixed or allowed to change.

10.2.38.4 Description

The keyword argument `element' can be any of the following:

`diff' - the diffusion tensor parameters. This will allow all diffusion tensor parameters to be toggled.

`all_spins' - using this keyword, all parameters from all spins will be toggled.

`all' - all parameter will be toggled. This is equivalent to combining both `diff' and `all_spins'.

The flag `fixed', if set to True, will fix parameters during optimisation whereas a value of False will allow parameters to vary.





10.2.39 frame_order.cone_pdb()

10.2.39.1 Synopsis

Create a PDB file representing the Frame Order cone models.

10.2.39.2 Defaults

frame_order.
[0]
[0]cone_pdb
(
[0]self, size=
[0]30.0, inc=
[0]40, file=
[0]`cone.
[0]pdb', dir=
[0]None, force=
[0]False)

10.2.39.3 Keyword Arguments

size: The size of the geometric object in Å.

inc: The number of increments used to create the geometric object.

file: The name of the PDB file to create.

dir: The directory where the file is to be located.

force: A flag which, if set to True, will overwrite the any pre-existing file.

10.2.39.4 Description

This function creates a PDB file containing an artificial geometric structure representing the Frame Order cone models.

There are four different types of residue within the PDB. The pivot point is represented as as a single carbon atom of the residue `PIV'. The cone consists of numerous H atoms of the residue `CON'. The cone axis vector is presented as the residue `AXE' with one carbon atom positioned at the pivot and the other $ x$ Åaway on the cone axis (set by the size argument). Finally, if Monte Carlo have been performed, there will be multiple `MCC' residues representing the cone for each simulation, and multiple `MCA' residues representing the multiple cone axes.

To create the diffusion in a cone PDB representation, a uniform distribution of vectors on a sphere is generated using spherical coordinates with the polar angle defined by the cone axis. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These are all placed into the PDB file as H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines representing the filled cone.





10.2.40 frame_order.domain_to_pdb()

10.2.40.1 Synopsis

Match the domains to PDB files.

10.2.40.2 Defaults

frame_order.
[0]
[0]domain_to_pdb
(
[0]self, domain=
[0]None, pdb=
[0]None)

10.2.40.3 Keyword Arguments

domain: The domain to associate the PDB file to.

pdb: The PDB file to associate the domain to.

10.2.40.4 Description

To display the frame order cone models within Pymol, the two domains need to be associated with PDB files. Then the reference domain will be fixed in the PDB frame, and the moving domain will be rotated to its average position.

10.2.40.5 Examples

To set the `N' domain to the PDB file `bax_N_1J7O_1 $ ^\mathrm{st}$ .pdb', type one of:


relax> frame_order.
[0]
[0]
[0]domain_to_pdb(
[0]
[0]`N', `bax_N_1J7O_1st.
[0]
[0]pdb')


relax> frame_order.
[0]
[0]
[0]domain_to_pdb(
[0]
[0]domain=
[0]
[0]`N', pdb=
[0]
[0]`bax_N_1J7O_1st.
[0]
[0]pdb')





10.2.41 frame_order.pivot()

10.2.41.1 Synopsis

Set the pivot point for the two body motion in the structural coordinate system.

10.2.41.2 Defaults

frame_order.
[0]pivot
(
[0]self, pivot=
[0]None)

10.2.41.3 Keyword Arguments

pivot: The pivot point for the motion (e.g. the position between the 2 domains in PDB coordinates).

10.2.41.4 Examples

To set the pivot point, type one of:


relax> frame_order.
[0]
[0]pivot(
[0]
[0][12.067, 14.313, -3.2675])


relax> frame_order.
[0]
[0]pivot(
[0]
[0]pivot=
[0]
[0][12.067, 14.313, -3.2675])





10.2.42 frame_order.ref_domain()

10.2.42.1 Synopsis

Set the reference domain for the `2-domain' Frame Order theories.

10.2.42.2 Defaults

frame_order.
[0]ref_domain
(
[0]self, ref=
[0]None)

10.2.42.3 Keyword Arguments

ref: The domain which will act as the frame of reference. This is only valid for the `2-domain' Frame Order theories.

10.2.42.4 Description

Prior to optimisation of the `2-domain' Frame Order theories, which of the two domains will act as the frame of reference must be specified. This is important for the attachment of cones to domains, etc.

10.2.42.5 Examples

To set up the isotropic cone frame order model with `centre' domain being the frame of reference, type:


relax> frame_order.
[0]
[0]ref_domain(
[0]
[0]ref=
[0]
[0]`centre')





10.2.43 frame_order.select_model()

10.2.43.1 Synopsis

Select and set up the Frame Order model.

10.2.43.2 Defaults

frame_order.
[0]select_model
(
[0]self, model=
[0]None)

10.2.43.3 Keyword Arguments

model: The name of the preset Frame Order model.

10.2.43.4 Description

Prior to optimisation, the Frame Order model should be selected. These models consist of three parameter categories:

- The average domain position. This includes the parameters ave_pos_alpha, ave_pos_beta, and ave_pos_gamma. These Euler angles rotate the tensors from the arbitrary PDB frame of the moving domain to the average domain position.
- The frame order eigenframe. This includes the parameters eigen_alpha, eigen_beta, and eigen_gamma. These Euler angles define the major modes of motion. The cone central axis is defined as the z-axis. The pseudo-elliptic cone $ x$ and y-axes are defined as the $ x$ and y-axes of the eigenframe.
- The cone parameters. These are defined as the tilt-torsion angles cone_theta_x, cone_theta_y, and cone_sigma_max. The cone_theta_x and cone_theta_y parameters define the two cone opening angles of the pseudo-ellipse. The amount of domain torsion is defined as the average domain position, plus and minus cone_sigma_max. The isotropic cones are defined by setting cone_theta_x = cone_theta_y and converting the single parameter into a 2 $ ^\mathrm{nd}$ rank order parameter.

The list of available models are:

`pseudo-ellipse' - The pseudo-elliptic cone model. This is the full model consisting of the parameters ave_pos_alpha, ave_pos_beta, ave_pos_gamma, eigen_alpha, eigen_beta, eigen_gamma, cone_theta_x, cone_theta_y, and cone_sigma_max.
`pseudo-ellipse, torsionless' - The pseudo-elliptic cone with the torsion angle cone_sigma_max set to zero.
`pseudo-ellipse, free rotor' - The pseudo-elliptic cone with no torsion angle restriction.
`iso cone' - The isotropic cone model. The cone is defined by a single order parameter s1 which is related to the single cone opening angle cone_theta_x = cone_theta_y. Due to rotational symmetry about the cone axis, the average position $ \alpha$ Euler angle ave_pos_alpha is dropped from the model. The symmetry also collapses the eigenframe to a single z-axis defined by the parameters axis_theta and axis_phi.
`iso cone, torsionless' - The isotropic cone model with the torsion angle cone_sigma_max set to zero.
`iso cone, free rotor' - The isotropic cone model with no torsion angle restriction.
`line' - The line cone model. This is the pseudo-elliptic cone with one of the cone angles, cone_theta_y, assumed to be statistically negligible. I.e. the cone angle is so small that it cannot be distinguished from noise.
`line, torsionless' - The line cone model with the torsion angle cone_sigma_max set to zero.
`line, free rotor' - The line cone model with no torsion angle restriction.
`rotor' - The only motion is a rotation about the cone axis restricted by the torsion angle cone_sigma_max.
`rigid' - No domain motions.
`free rotor' - The only motion is free rotation about the cone axis.

10.2.43.5 Examples

To select the isotropic cone model, type:


relax> frame_order.
[0]
[0]select_model(
[0]
[0]model=
[0]
[0]`iso cone')





10.2.44 frq.set()

10.2.44.1 Synopsis

Set the spectrometer frequency of the experiment.

10.2.44.2 Defaults

frq.
[0]set
(
[0]self, id=
[0]None, frq=
[0]None)

10.2.44.3 Keyword arguments

id: The experiment identification string.

frq: The spectrometer frequency in Hertz.

10.2.44.4 Description

This user function allows the spectrometer frequency of a given experiment to be set.






10.2.45 grace.view()

10.2.45.1 Synopsis

Function for running Grace.

10.2.45.2 Defaults

grace.
[0]view
(
[0]self, file=
[0]None, dir=
[0]`grace', grace_exe=
[0]`xmgrace')

10.2.45.3 Keyword Arguments

file: The name of the file.

dir: The directory name.

grace_exe: The Grace executable file.

10.2.45.4 Description

This function can be used to execute Grace to view the specified file the Grace `.agr' file and the execute Grace. If the directory name is set to None, the file will be assumed to be in the current working directory.

10.2.45.5 Examples

To view the file `s2.agr' in the directory `grace', type:


relax> grace.
[0]
[0]view(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]
[0]agr')


relax> grace.
[0]
[0]view(
[0]
[0]file=
[0]
[0]`s2.
[0]
[0]
[0]agr', dir=
[0]
[0]`grace')






10.2.46 grace.write()

10.2.46.1 Synopsis

Function for creating a grace `.agr' file.

10.2.46.2 Defaults

grace.
[0]write
(
[0]self, x_data_type=
[0]`spin', y_data_type=
[0]None, spin_id=
[0]None, plot_data=
[0]`value', file=
[0]None, dir=
[0]`grace', force=
[0]False, norm=
[0]False)

10.2.46.3 Keyword Arguments

x_data_type: The data type for the X-axis (no regular expression is allowed).

$ y$ _data_type: The data type for the Y-axis (no regular expression is allowed).

spin_id: The spin identification string.

plot_data: The data to use for the plot.

norm: Flag for the normalisation of series type data.

file: The name of the file.

dir: The directory name.

force: A flag which, if set to True, will cause the file to be overwritten.

10.2.46.4 Description

This function is designed to be as flexible as possible so that any combination of data can be plotted. The output is in the format of a Grace plot (also known as ACE/gr, Xmgr, and xmgrace) which only supports two dimensional plots. Three types of keyword arguments can be used to create various types of plot. These include the X-axis and Y-axis data types, the spin identification string, and an argument for selecting what to actually plot.

The X-axis and Y-axis data type arguments should be plain strings, regular expression is not allowed. If the X-axis data type argument is not given, the plot will default to having the spin sequence along the x-axis. The two axes of the Grace plot can be absolutely any of the data types listed in the tables below. The only limitation, currently anyway, is that the data must belong to the same data pipe.

The spin identification string can be used to limit which spins are used in the plot. The default is that all spins will be used, however, these arguments can be used to select a subset of all spins, or a single spin for plots of Monte Carlo simulations, etc.

The property which is actually plotted can be controlled by the `plot_data' argument. It can be one of the following:

`value' -
Plot values (with errors if they exist).
`error' -
Plot errors.
`sims' -
Plot the simulation values.

Normalisation is only allowed for series type data, for example the R$ _2$ exponential curves, and will be ignored for all other data types. If the norm flag is set to True then the y-value of the first point of the series will be set to 1. This normalisation is useful for highlighting errors in the data sets.

10.2.46.5 Examples

To write the NOE values for all spins to the Grace file `noe.agr', type one of:


relax> grace.
[0]
[0]write(
[0]
[0]`spin', `noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr')


relax> grace.
[0]
[0]write(
[0]
[0]y_data_type=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr')


relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`spin', y_data_type=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr')


relax> grace.
[0]
[0]write(
[0]
[0]y_data_type=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]
[0]agr', force=
[0]
[0]True)

To create a Grace file of `S2' vs. `te' for all spins, type one of:


relax> grace.
[0]
[0]write(
[0]
[0]`S2', `te', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')


relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`S2', y_data_type=
[0]
[0]`te', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')


relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`S2', y_data_type=
[0]
[0]`te', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr', force=
[0]
[0]True)

To create a Grace file of the Monte Carlo simulation values of `Rex' vs. `te' for residue 123, type one of:


relax> grace.
[0]
[0]write(
[0]
[0]`Rex', `te', spin_id=
[0]
[0]`:123', plot_data=
[0]
[0]`sims', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')


relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`Rex', y_data_type=
[0]
[0]`te', spin_id=
[0]
[0]`:123', plot_data=
[0]
[0]`sims', file=
[0]
[0]`s2_te.
[0]
[0]
[0]agr')

By plotting the peak intensities, the integrity of exponential relaxation curves can be checked and anomalies searched for prior to model-free analysis or reduced spectral density mapping. For example the normalised average peak intensities can be plotted verses the relaxation time periods for the relaxation curves of all residues of a protein. The normalisation, whereby the initial peak intensity of each residue I(0) is set to 1, emphasises any problems. To produce this Grace file, type:


relax> grace.
[0]
[0]write(
[0]
[0]x_data_type=
[0]
[0]`relax_times', y_data_type=
[0]
[0]`ave_int', file=
[0]
[0]`intensities_norm.
[0]
[0]
[0]agr', force=
[0]
[0]True, norm=
[0]
[0]True)


10.2.46.6 Regular expression

The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.

This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:

`[]' -
A sequence or set of characters to match to a single character. For example, `[Ss]2' will match both `S2' and `s2'.
`^' -
Match the start of the string.
`$' -
Match the end of the string. For example, `^[Ss]2$' will match `s2' but not `S2f' or `s2s'.
`.' -
Match any character.
`x*' -
Match the character `x' any number of times, for example `x' will match, as will `xxxxx'
`.*' -
Match any sequence of characters of any length.

Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.


10.2.46.7 Minimisation statistic data type string matching patterns

(see table 10.4)

Table: First table for the grace.write() user function.
Data type Object name Patterns
Chi-squared statistic `chi2' `^[Cc]hi2$' or `^[Cc]hi[-_ ][Ss]quare'
Iteration count `iter' `^[Ii]ter'
Function call count `f_count' `^[Ff].*[ -_][Cc]ount'
Gradient call count `g_count' `^[Gg].*[ -_][Cc]ount'
Hessian call count `h_count' `^[Hh].*[ -_][Cc]ount'

10.2.46.8 NOE calculation data type string matching patterns

(see table 10.5)

Table: Second table for the grace.write() user function.
Data type Object name Patterns
Reference intensity `ref' `^[Rr]ef$' or `[Rr]ef[ -_][Ii]nt'
Saturated intensity `sat' `^[Ss]at$' or `[Ss]at[ -_][Ii]nt'
NOE `noe' `^[Nn][Oo][Ee]$'


10.2.46.9 Relaxation curve fitting data type string matching patterns

(see table 10.6)

Table: Third table for the grace.write() user function.
Data type Object name Patterns
Relaxation rate `rx' `^[Rr]x$'
Peak intensities (series) `intensities' `^[Ii]nt$'
Initial intensity `i0' `^[Ii]0$'
Intensity at infinity `iinf' `^[Ii]inf$'
Relaxation period times (series) `relax_times' `^[Rr]elax[ -_][Tt]imes$'


10.2.46.10 Reduced spectral density mapping data type string matching patterns

(see table 10.7)

Table: Fourth table for the grace.write() user function.
Data type Object name Patterns
$ J(0)$ `j0' `^[Jj]0$' or `[Jj] $ \backslash$ (0 $ \backslash$ )'
$ J(\omega_X)$ `jwx' `^[Jj]w[Xx]$' or `[Jj] $ \backslash$ (w[Xx] $ \backslash$ )'
$ J(\omega_H)$ `jwh' `^[Jj]w[Hh]$' or `[Jj] $ \backslash$ (w[Hh] $ \backslash$ )'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'

10.2.46.11 Model-free data type string matching patterns

(see table 10.8)

Table: Fifth table for the grace.write() user function.
Data type Object name Patterns
Local $ \tau _m$ `local_tm' `[Ll]ocal[ -_]tm'
Order parameter $ S^2$ `s2' `^[Ss]2$'
Order parameter $ S^2_f$ `s2f' `^[Ss]2f$'
Order parameter $ S^2_s$ `s2s' `^[Ss]2s$'
Correlation time $ \tau _e$ `te' `^te$'
Correlation time $ \tau _f$ `tf' `^tf$'
Correlation time $ \tau _s$ `ts' `^ts$'
Chemical exchange `rex' `^[Rr]ex$' or `[Cc]emical[ -_][Ee]xchange'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'





10.2.47 grid_search()

10.2.47.1 Synopsis

The grid search function.

10.2.47.2 Defaults

grid_search(
[0]self, lower=
[0]None, upper=
[0]None, inc=
[0]21, constraints=
[0]True, verbosity=
[0]1)

10.2.47.3 Keyword Arguments

lower: An array of the lower bound parameter values for the grid search. The length of the array should be equal to the number of parameters in the model.

upper: An array of the upper bound parameter values for the grid search. The length of the array should be equal to the number of parameters in the model.

inc: The number of increments to search over. If a single integer is given then the number of increments will be equal in all dimensions. Different numbers of increments in each direction can be set if `inc' is set to an array of integers of length equal to the number of parameters.

constraints: A boolean flag specifying whether the parameters should be constrained. The default is to turn constraints on (constraints=True).

verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.





10.2.48 intro_off()

10.2.48.1 Synopsis

Turn the function introductions off.

10.2.48.2 Defaults

intro_off(
[0]self, verbose=
[0]True)





10.2.49 intro_on()

10.2.49.1 Synopsis

Turn the function introductions on.

10.2.49.2 Defaults

intro_on(
[0]self, verbose=
[0]True)





10.2.50 jw_mapping.set_frq()

10.2.50.1 Synopsis

Function for selecting which relaxation data to use in the $ J(\omega )$ mapping.

10.2.50.2 Defaults

jw_mapping.
[0]set_frq
(
[0]self, frq=
[0]None)

10.2.50.3 Keyword Arguments

frq: The spectrometer frequency in Hz.

10.2.50.4 Description

This function will select the relaxation data to use in the reduced spectral density mapping corresponding to the given frequency.

10.2.50.5 Examples


relax> jw_mapping.
[0]
[0]set_frq(
[0]
[0]600.0 * 1e6)


relax> jw_mapping.
[0]
[0]set_frq(
[0]
[0]frq=
[0]
[0]600.0 * 1e6)






10.2.51 minimise()

10.2.51.1 Synopsis

Minimisation function.

10.2.51.2 Defaults

minimise(
[0]self, *args, **keywords)

10.2.51.3 Arguments

The arguments, which should all be strings, specify the minimiser as well as its options. A minimum of one argument is required. As this calls the minfx function `generic_minimise' the full list of allowed arguments is shown below in the reproduced `generic_minimise' docstring. Ignore all sections except those labelled as minimisation algorithms and minimisation options. Also do not select the Method of Multipliers constraint algorithm as this is used in combination with the given minimisation algorithm if the keyword argument `constraints' is set to 1. The grid search algorithm should also not be selected as this is accessed using the `grid' function instead. The first argument passed will be set to the minimisation algorithm while all other arguments will be set to the minimisation options.

Keyword arguments differ from normal arguments having the form `keyword = value'. All arguments must precede keyword arguments in python. For more information see the examples section below or the python tutorial.

10.2.51.4 Keyword Arguments

func_tol: The function tolerance. This is used to terminate minimisation once the function value between iterations is less than the tolerance. The default value is 1e-25.

grad_tol: The gradient tolerance. Minimisation is terminated if the current gradient value is less than the tolerance. The default value is None.

max_iterations: The maximum number of iterations. The default value is 1e7.

constraints: A boolean flag specifying whether the parameters should be constrained. The default is to turn constraints on (constraints=True).

scaling: The diagonal scaling boolean flag. The default that scaling is on (scaling=True).

verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.

10.2.51.5 Diagonal scaling

Diagonal scaling is the transformation of parameter values such that each value has a similar order of magnitude. Certain minimisation techniques, for example the trust region methods, perform extremely poorly with badly scaled problems. In addition, methods which are insensitive to scaling such as Newton minimisation may still benefit due to the minimisation of round off errors.

In Model-free analysis for example, if $ S^2$ = 0.5, $ \tau _e$ = 200 ps, and $ R_{ex}$ = 15 1/s at 600 MHz, the unscaled parameter vector would be [0.5, 2.0e-10, 1.055e-18]. $ R_{ex}$ is divided by (2 * $ \pi$ * 600,000,000)**2 to make it field strength independent. The scaling vector for this model may be something like [1.0, 1e-9, 1/(2 * $ \pi$ * 6e8)**2]. By dividing the unscaled parameter vector by the scaling vector the scaled parameter vector is [0.5, 0.2, 15.0]. To revert to the original unscaled parameter vector, the scaled parameter vector and scaling vector are multiplied.

10.2.51.6 Examples

To apply Newton minimisation together with the GMW81 Hessian modification algorithm, the More and Thuente line search algorithm, a function tolerance of 1e-25, no gradient tolerance, a maximum of 10,000,000 iterations, constraints turned on to limit parameter values, and have normal printout, type any combination of:


relax> minimise(
[0]
[0]`newton')


relax> minimise(
[0]
[0]`Newton')


relax> minimise(
[0]
[0]`newton', `gmw')


relax> minimise(
[0]
[0]`newton', `mt')


relax> minimise(
[0]
[0]`newton', `gmw', `mt')


relax> minimise(
[0]
[0]`newton', `mt', `gmw')


relax> minimise(
[0]
[0]`newton', func_tol=
[0]
[0]1e-25)


relax> minimise(
[0]
[0]`newton', func_tol=
[0]
[0]1e-25, grad_tol=
[0]
[0]None)


relax> minimise(
[0]
[0]`newton', max_iter=
[0]
[0]1e7)


relax> minimise(
[0]
[0]`newton', constraints=
[0]
[0]True, max_iter=
[0]
[0]1e7)


relax> minimise(
[0]
[0]`newton', verbosity=
[0]
[0]1)

To use constrained Simplex minimisation with a maximum of 5000 iterations, type:


relax> minimise(
[0]
[0]`simplex', constraints=
[0]
[0]True, max_iter=
[0]
[0]5000)

10.2.51.7 Note

All the text which follows is a reproduction of the docstring of the generic_minimise function from the minfx python package. Only take note of the minimisation algorithms and minimisation options sections, the other sections are not relevant for this function. The Grid search and Method of Multipliers algorithms CANNOT be selected as minimisation algorithms for this function.

The section entitled Keyword Arguments is also completely inaccessible therefore please ignore that text.

Generic minimisation function.

This is a generic function which can be used to access all minimisers using the same set of function arguments. These are the function tolerance value for convergence tests, the maximum number of iterations, a flag specifying which data structures should be returned, and a flag specifying the amount of detail to print to screen.

10.2.51.8 Keyword Arguments

func: The function which returns the value.

dfunc: The function which returns the gradient.

d2func: The function which returns the Hessian.

args: The tuple of arguments to supply to the functions func, dfunc, and d2func.

x0: The vector of initial parameter value estimates (as an array).

min_algor: A string specifying which minimisation technique to use.

min_options: A tuple to pass to the minimisation function as the min_options keyword.

func_tol: The function tolerance value. Once the function value between iterations decreases below this value, minimisation is terminated.

grad_tol: The gradient tolerance value.

maxiter: The maximum number of iterations.

A: Linear constraint matrix m*n (A.x $ \ge$ $ b$ ).

$ b$ : Linear constraint scalar vector (A.x $ \ge$ $ b$ ).

$ l$ : Lower bound constraint vector ($ l$ $ \le$ $ x$ $ \le$ $ u$ ).

$ u$ : Upper bound constraint vector ($ l$ $ \le$ $ x$ $ \le$ $ u$ ).

c: User supplied constraint function.

dc: User supplied constraint gradient function.

d2c: User supplied constraint Hessian function.

full_output: A flag specifying which data structures should be returned.

print_flag: A flag specifying how much information should be printed to standard output during minimisation. 0 means no output, 1 means minimal output, and values above 1 increase the amount of output printed.


10.2.51.9 Minimisation output

The following values of the `full_output' flag will return, in tuple form, the following data

0 -
`xk',
1 -
`(xk, fk, $ k$ , f_count, g_count, h_count, warning)',

where the data names correspond to

`xk' -
The array of minimised parameter values,
`fk' -
The minimised function value,
`k' -
The number of iterations,
`f_count' -
The number of function calls,
`g_count' -
The number of gradient calls,
`h_count' -
The number of Hessian calls,
`warning' -
The warning string.


10.2.51.10 Minimisation algorithms

A minimisation function is selected if the minimisation algorithm argument, which should be a string, matches a certain pattern. Because the python regular expression `match' statement is used, various strings can be supplied to select the same minimisation algorithm. Below is a list of the minimisation algorithms available together with the corresponding patterns.

This is a short description of python regular expression, for more information, see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:

`[]' -
A sequence or set of characters to match to a single character. For example, `[Nn]ewton' will match both `Newton' and `newton'.
`^' -
Match the start of the string.
`$' -
Match the end of the string. For example, `^[Ll][Mm]$' will match `lm' and `LM' but will not match if characters are placed either before or after these strings.

To select a minimisation algorithm, set the argument to a string which matches the given pattern.

Unconstrained line search methods:

(see table 10.9)

Table 10.9: First table for the minimise() user function.
Minimisation algorithm Patterns
Back-and-forth coordinate descent `^[Cc][Dd]$' or `^[Cc]oordinate[ _-][Dd]escent$'
Steepest descent `^[Ss][Dd]$' or `^[Ss]teepest[ _-][Dd]escent$'
Quasi-Newton BFGS `^[Bb][Ff][Gg][Ss]$'
Newton `^[Nn]ewton$'
Newton-CG `^[Nn]ewton[ _-][Cc][Gg]$' or `^[Nn][Cc][Gg]$'

Unconstrained trust-region methods:

(see table 10.10)

Table 10.10: Second table for the minimise() user function.
Minimisation algorithm Patterns
Cauchy point `^[Cc]auchy'
Dogleg `^[Dd]ogleg'
CG-Steihaug `^[Cc][Gg][-_ ][Ss]teihaug' or `^[Ss]teihaug'
Exact trust region `^[Ee]xact'

Unconstrained conjugate gradient methods:

(see table 10.11)

Table 10.11: Third table for the minimise() user function.
Minimisation algorithm Patterns
Fletcher-Reeves `^[Ff][Rr]$' or `^[Ff]letcher[-_ ][Rr]eeves$'
Polak-Ribière `^[Pp][Rr]$' or `^[Pp]olak[-_ ][Rr]ibiere$'
Polak-Ribière + `^[Pp][Rr] $ \backslash$ +$' or `^[Pp]olak[-_ ][Rr]ibiere $ \backslash$ +$'
Hestenes-Stiefel `^[Hh][Ss]$' or `^[Hh]estenes[-_ ][Ss]tiefel$'

Miscellaneous unconstrained methods:

(see table 10.12)

Table 10.12: Fourth table for the minimise() user function.
Minimisation algorithm Patterns
Simplex `^[Ss]implex$'
Levenberg-Marquardt `^[Ll][Mm]$' or `^[Ll]evenburg-[Mm]arquardt$'

Constrained methods:

(see table 10.13)

Table 10.13: Fifth table for the minimise() user function.
Minimisation algorithm Patterns
Method of Multipliers `^[Mm][Oo][Mm]$' or `[Mm]ethod of [Mm]ultipliers$'


10.2.51.11 Minimisation options

The minimisation options can be given in any order.

Line search algorithms. These are used in the line search methods and the conjugate gradient methods. The default is the Backtracking line search.

(see table 10.14)

Table 10.14: Sixth table for the minimise() user function.
Line search algorithm Patterns
Backtracking line search `^[Bb]ack'
Nocedal and Wright interpolation `^[Nn][Ww][Ii]' or
based line search `^[Nn]ocedal[ _][Ww]right[ _][Ii]nt'
Nocedal and Wright line search `^[Nn][Ww][Ww]' or
for the Wolfe conditions `^[Nn]ocedal[ _][Ww]right[ _][Ww]olfe'
More and Thuente line search `^[Mm][Tt]' or `^[Mm]ore[ _][Tt]huente$'
No line search `^[Nn]o [Ll]ine [Ss]earch$'

Hessian modifications. These are used in the Newton, Dogleg, and Exact trust region algorithms.

(see table 10.15)

Table 10.15: Seventh table for the minimise() user function.
Hessian modification Patterns
Unmodified Hessian `^[Nn]o [Hh]essian [Mm]od'
Eigenvalue modification `^[Ee]igen'
Cholesky with added multiple of `^[Cc]hol'
the identity
The Gill, Murray, and Wright `^[Gg][Mm][Ww]$'
modified Cholesky algorithm
The Schnabel and Eskow 1999 `^[Ss][Ee]99'
algorithm

Hessian type, these are used in a few of the trust region methods including the Dogleg and Exact trust region algorithms. In these cases, when the Hessian type is set to Newton, a Hessian modification can also be supplied as above. The default Hessian type is Newton, and the default Hessian modification when Newton is selected is the GMW algorithm.

(see table 10.16)

Table 10.16: Eighth table for the minimise() user function.
Hessian type Patterns
Quasi-Newton BFGS `^[Bb][Ff][Gg][Ss]$'
Newton `^[Nn]ewton$'

For Newton minimisation, the default line search algorithm is the More and Thuente line search, while the default Hessian modification is the GMW algorithm.





10.2.52 model_free.create_model()

10.2.52.1 Synopsis

Function to create a model-free model.

10.2.52.2 Defaults

model_free.
[0]
[0]create_model
(
[0]self, model=
[0]None, equation=
[0]None, params=
[0]None, spin_id=
[0]None)

10.2.52.3 Keyword Arguments

model: The name of the model-free model.

equation: The model-free equation.

params: The array of parameter names of the model.

spin_id: The spin identification string.

10.2.52.4 Model-free equation

`mf_orig' selects the original model-free equations with parameters {$ S^2$ , $ \tau _e$ }. `mf_ext' selects the extended model-free equations with parameters {$ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ }. `mf_ext2' selects the extended model-free equations with parameters {$ S^2_f$ , $ \tau _f$ , $ S^2_s$ , $ \tau _s$ }.

10.2.52.5 Model-free parameters

The following parameters are accepted for the original model-free equation:

`S2' -
The square of the generalised order parameter.
`te' -
The effective correlation time.

The following parameters are accepted for the extended model-free equation:

`S2f' -
The square of the generalised order parameter of the faster motion.
`tf' -
The effective correlation time of the faster motion.
`S2' -
The square of the generalised order parameter $ S^2$ = $ S^2_f$ * $ S^2_s$ .
`ts' -
The effective correlation time of the slower motion.

The following parameters are accepted for the extended 2 model-free equation:

`S2f' -
The square of the generalised order parameter of the faster motion.
`tf' -
The effective correlation time of the faster motion.
`S2s' -
The square of the generalised order parameter of the slower motion.
`ts' -
The effective correlation time of the slower motion.

The following parameters are accepted for all equations:

`Rex' -
The chemical exchange relaxation.
`r' -
The average bond length $ <$ $ r$ $ >$ .
`CSA' -
The chemical shift anisotropy.

10.2.52.6 Spin identification string

If `spin_id' is supplied then the model will only be created for the corresponding spins. Otherwise the model will be created for all spins.

10.2.52.7 Examples

The following commands will create the model-free model `m1' which is based on the original model-free equation and contains the single parameter `S2'.


relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]`m1', `mf_orig', [`S2'])


relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]model=
[0]
[0]`m1', params=
[0]
[0][`S2'], equation=
[0]
[0]`mf_orig')

The following commands will create the model-free model `large_model' which is based on the extended model-free equation and contains the seven parameters `S2f', `tf', `S2', `ts', `Rex', `CSA', `r'.


relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]`large_model', `mf_ext', [`S2f', `tf', `S2', `ts', `Rex', `CSA', `r'])


relax> model_free.
[0]
[0]
[0]create_model(
[0]
[0]model=
[0]
[0]`large_model', params=
[0]
[0][`S2f', `tf', `S2', `ts', `Rex', `CSA', `r'], equation=
[0]
[0]`mf_ext')





10.2.53 model_free.delete()

10.2.53.1 Synopsis

Function for deleting all model-free data from the current data pipe.

10.2.53.2 Defaults

model_free.
[0]
[0]delete
(
[0]self)

10.2.53.3 Examples

To delete all model-free data, type:


relax> model_free.
[0]
[0]
[0]delete(
[0]
[0])





10.2.54 model_free.remove_tm()

10.2.54.1 Synopsis

Function for removing the local $ \tau _m$ parameter from a model.

10.2.54.2 Defaults

model_free.
[0]remove_tm
(
[0]self, spin_id=
[0]None)

10.2.54.3 Keyword Arguments

spin_id: The spin identification string.

10.2.54.4 Description

This function will remove the local $ \tau _m$ parameter from the model-free parameter set. If there is no local $ \tau _m$ parameter within the set nothing will happen.

If no spin identification string is given, then the function will apply to all spins.

10.2.54.5 Examples

The following command will remove the parameter `tm':


relax> model_free.
[0]
[0]remove_tm(
[0]
[0])





10.2.55 model_free.select_model()

10.2.55.1 Synopsis

Function for the selection of a preset model-free model.

10.2.55.2 Defaults

model_free.
[0]select_model
(
[0]self, model=
[0]None, spin_id=
[0]None)

10.2.55.3 Keyword Arguments

model: The name of the preset model.

10.2.55.4 The preset models

The standard preset model-free models are

`m0' = {},
`m1' = {S2},
`m2' = {$ S^2$ , $ \tau _e$ },
`m3' = {$ S^2$ , $ R_{ex}$ },
`m4' = {$ S^2$ , $ \tau _e$ , $ R_{ex}$ },
`m5' = {$ S^2_f$ , $ S^2$ , $ \tau _s$ },
`m6' = {$ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ },
`m7' = {$ S^2_f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`m8' = {$ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`m9' = {Rex}.

The preset model-free models with optimisation of the CSA value are

`m10' = {CSA},
`m11' = {CSA, $ S^2$ },
`m12' = {CSA, $ S^2$ , $ \tau _e$ },
`m13' = {CSA, $ S^2$ , $ R_{ex}$ },
`m14' = {CSA, $ S^2$ , $ \tau _e$ , $ R_{ex}$ },
`m15' = {CSA, $ S^2_f$ , $ S^2$ , $ \tau _s$ },
`m16' = {CSA, $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ },
`m17' = {CSA, $ S^2_f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`m18' = {CSA, $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`m19' = {CSA, $ R_{ex}$ }.

The preset model-free models with optimisation of the bond length are

`m20' = {r},
`m21' = {$ r$ , $ S^2$ },
`m22' = {$ r$ , $ S^2$ , $ \tau _e$ },
`m23' = {$ r$ , $ S^2$ , $ R_{ex}$ },
`m24' = {$ r$ , $ S^2$ , $ \tau _e$ , $ R_{ex}$ },
`m25' = {$ r$ , $ S^2_f$ , $ S^2$ , $ \tau _s$ },
`m26' = {$ r$ , $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ },
`m27' = {$ r$ , $ S^2_f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`m28' = {$ r$ , $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`m29' = {$ r$ , CSA, $ R_{ex}$ }.

The preset model-free models with both optimisation of the bond length and CSA are

`m30' = {$ r$ , CSA},
`m31' = {$ r$ , CSA, $ S^2$ },
`m32' = {$ r$ , CSA, $ S^2$ , $ \tau _e$ },
`m33' = {$ r$ , CSA, $ S^2$ , $ R_{ex}$ },
`m34' = {$ r$ , CSA, $ S^2$ , $ \tau _e$ , $ R_{ex}$ },
`m35' = {$ r$ , CSA, $ S^2_f$ , $ S^2$ , $ \tau _s$ },
`m36' = {$ r$ , CSA, $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ },
`m37' = {$ r$ , CSA, $ S^2_f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`m38' = {$ r$ , CSA, $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`m39' = {$ r$ , CSA, $ R_{ex}$ }.

Warning: The models in the thirties range fail when using standard R$ _1$ , R$ _2$ , and NOE relaxation data. This is due to the extreme flexibly of these models where a change in the parameter `r' is compensated by a corresponding change in the parameter `CSA' and vice versa.

Additional preset model-free models, which are simply extensions of the above models with the addition of a local $ \tau _m$ parameter are:

`tm0' = {tm},
`tm1' = {$ \tau _m$ , $ S^2$ },
`tm2' = {$ \tau _m$ , $ S^2$ , $ \tau _e$ },
`tm3' = {$ \tau _m$ , $ S^2$ , $ R_{ex}$ },
`tm4' = {$ \tau _m$ , $ S^2$ , $ \tau _e$ , $ R_{ex}$ },
`tm5' = {$ \tau _m$ , $ S^2_f$ , $ S^2$ , $ \tau _s$ },
`tm6' = {$ \tau _m$ , $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ },
`tm7' = {$ \tau _m$ , $ S^2_f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`tm8' = {$ \tau _m$ , $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`tm9' = {$ \tau _m$ , $ R_{ex}$ }.

The preset model-free models with optimisation of the CSA value are

`tm10' = {$ \tau _m$ , CSA},
`tm11' = {$ \tau _m$ , CSA, $ S^2$ },
`tm12' = {$ \tau _m$ , CSA, $ S^2$ , $ \tau _e$ },
`tm13' = {$ \tau _m$ , CSA, $ S^2$ , $ R_{ex}$ },
`tm14' = {$ \tau _m$ , CSA, $ S^2$ , $ \tau _e$ , $ R_{ex}$ },
`tm15' = {$ \tau _m$ , CSA, $ S^2_f$ , $ S^2$ , $ \tau _s$ },
`tm16' = {$ \tau _m$ , CSA, $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ },
`tm17' = {$ \tau _m$ , CSA, $ S^2_f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`tm18' = {$ \tau _m$ , CSA, $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`tm19' = {$ \tau _m$ , CSA, $ R_{ex}$ }.

The preset model-free models with optimisation of the bond length are

`tm20' = {$ \tau _m$ , $ r$ },
`tm21' = {$ \tau _m$ , $ r$ , $ S^2$ },
`tm22' = {$ \tau _m$ , $ r$ , $ S^2$ , $ \tau _e$ },
`tm23' = {$ \tau _m$ , $ r$ , $ S^2$ , $ R_{ex}$ },
`tm24' = {$ \tau _m$ , $ r$ , $ S^2$ , $ \tau _e$ , $ R_{ex}$ },
`tm25' = {$ \tau _m$ , $ r$ , $ S^2_f$ , $ S^2$ , $ \tau _s$ },
`tm26' = {$ \tau _m$ , $ r$ , $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ },
`tm27' = {$ \tau _m$ , $ r$ , $ S^2_f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`tm28' = {$ \tau _m$ , $ r$ , $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`tm29' = {$ \tau _m$ , $ r$ , CSA, $ R_{ex}$ }.

The preset model-free models with both optimisation of the bond length and CSA are

`tm30' = {$ \tau _m$ , $ r$ , CSA},
`tm31' = {$ \tau _m$ , $ r$ , CSA, $ S^2$ },
`tm32' = {$ \tau _m$ , $ r$ , CSA, $ S^2$ , $ \tau _e$ },
`tm33' = {$ \tau _m$ , $ r$ , CSA, $ S^2$ , $ R_{ex}$ },
`tm34' = {$ \tau _m$ , $ r$ , CSA, $ S^2$ , $ \tau _e$ , $ R_{ex}$ },
`tm35' = {$ \tau _m$ , $ r$ , CSA, $ S^2_f$ , $ S^2$ , $ \tau _s$ },
`tm36' = {$ \tau _m$ , $ r$ , CSA, $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ },
`tm37' = {$ \tau _m$ , $ r$ , CSA, $ S^2_f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`tm38' = {$ \tau _m$ , $ r$ , CSA, $ S^2_f$ , $ \tau _f$ , $ S^2$ , $ \tau _s$ , $ R_{ex}$ },
`tm39' = {$ \tau _m$ , $ r$ , CSA, $ R_{ex}$ }.

10.2.55.5 Spin identification string

If `spin_id' is supplied then the model will only be selected for the corresponding spins. Otherwise the model will be selected for all spins.

10.2.55.6 Examples

To pick model `m1' for all selected spins, type:


relax> model_free.
[0]
[0]select_model(
[0]
[0]`m1')


relax> model_free.
[0]
[0]select_model(
[0]
[0]model=
[0]
[0]`m1')





10.2.56 model_selection()

10.2.56.1 Synopsis

Function for model selection.

10.2.56.2 Defaults

model_selection(
[0]self, method=
[0]None, modsel_pipe=
[0]None, pipes=
[0]None)

10.2.56.3 Keyword arguments

method: The model selection technique (see below).

modsel_pipe: The name of the new data pipe which will be created by this user function by the copying of the selected data pipe.

pipes: An array containing the names of all data pipes to include in model selection.

10.2.56.4 Description

The following model selection methods are supported:

AIC -
Akaike's Information Criteria.
AICc -
Small sample size corrected AIC.
BIC -
Bayesian or Schwarz Information Criteria.
Bootstrap -
Bootstrap model selection.
CV -
Single-item-out cross-validation.
Expect -
The expected overall discrepancy (the true values of the parameters are required).
Farrow -
Old model-free method by Farrow et al., 1994.
Palmer -
Old model-free method by Mandel et al., 1995.
Overall -
The realised overall discrepancy (the true values of the parameters are required).

For the methods `Bootstrap', `Expect', and `Overall', the function `monte_carlo' should have previously been executed with the type argument set to the appropriate value to modify its behaviour.

If the pipes argument is not supplied then all data pipes will be used for model selection.

10.2.56.5 Example

For model-free analysis, if the preset models 1 to 5 are minimised and loaded into the program, the following commands will carry out AIC model selection and to place the selected results into the `mixed' data pipe, type one of:


relax> model_selection(
[0]
[0]`AIC', `mixed')


relax> model_selection(
[0]
[0]method=
[0]
[0]`AIC', modsel_pipe=
[0]
[0]`mixed')


relax> model_selection(
[0]
[0]`AIC', `mixed', [`m1', `m2', `m3', `m4', `m5'])


relax> model_selection(
[0]
[0]method=
[0]
[0]`AIC', modsel_pipe=
[0]
[0]`mixed', pipes=
[0]
[0][`m1', `m2', `m3', `m4', `m5'])






10.2.57 molecule.copy()

10.2.57.1 Synopsis

Function for copying all data associated with a molecule.

10.2.57.2 Defaults

molecule.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, mol_from=
[0]None, pipe_to=
[0]None, mol_to=
[0]None)

10.2.57.3 Keyword Arguments

pipe_from: The data pipe containing the molecule from which the data will be copied. This defaults to the current data pipe.

mol_from: The molecule identifier string of the molecule to copy the data from.

pipe_to: The data pipe to copy the data to. This defaults to the current data pipe.

mol_to: The molecule identifier string of the molecule to copy the data to.

10.2.57.4 Description

This function will copy all the data associated with a molecule to a second molecule. This includes residue and spin system information. The new molecule must not yet exist.

10.2.57.5 Examples

To copy the molecule data from the molecule `GST' to the new molecule `wt-GST', type:


relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]`#GST', `#wt-GST')


relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]mol_from=
[0]
[0]`#GST', mol_to=
[0]
[0]`#wt-GST')

To copy the molecule data of the molecule `Ap4Aase' from the data pipe `m1' to `m2', assuming the current data pipe is `m1', type:


relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]mol_from=
[0]
[0]`#ApAase', pipe_to=
[0]
[0]`m2')


relax> molecule.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', mol_from=
[0]
[0]`#ApAase', pipe_to=
[0]
[0]`m2', mol_to=
[0]
[0]`#ApAase')

10.2.57.6 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.






10.2.58 molecule.create()

10.2.58.1 Synopsis

Function for creating a new molecule.

10.2.58.2 Defaults

molecule.
[0]
[0]create
(
[0]self, mol_name=
[0]None, type=
[0]None)

10.2.58.3 Keyword Arguments

mol_name: The name of the molecule.

type: The type of molecule.

10.2.58.4 Description

This function will add a new molecule data container to the relax data storage object. The same molecule name cannot be used more than once. The molecule type need not be specified. However if it given, it should be one of `protein', `RNA', `DNA', `organic molecule', `inorganic molecule', `other'.

10.2.58.5 Examples

To create the molecules `Ap4Aase', `ATP', and `MgF4', type:


relax> molecule.
[0]
[0]
[0]create(
[0]
[0]`Ap4Aase')


relax> molecule.
[0]
[0]
[0]create(
[0]
[0]`ATP')


relax> molecule.
[0]
[0]
[0]create(
[0]
[0]`MgF4')






10.2.59 molecule.delete()

10.2.59.1 Synopsis

Function for deleting molecules.

10.2.59.2 Defaults

molecule.
[0]
[0]delete
(
[0]self, mol_id=
[0]None)

10.2.59.3 Keyword Arguments

mol_id: The molecule identifier string.

10.2.59.4 Description

This function can be used to delete a single or sets of molecules.

10.2.59.5 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.






10.2.60 molecule.display()

10.2.60.1 Synopsis

Function for displaying the molecule information.

10.2.60.2 Defaults

molecule.
[0]
[0]display
(
[0]self, mol_id=
[0]None)

10.2.60.3 Keyword Arguments

mol_id: The molecule identifier string.

10.2.60.4 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.






10.2.61 molecule.name()

10.2.61.1 Synopsis

Function for naming a molecule.

10.2.61.2 Defaults

molecule.
[0]name
(
[0]self, mol_id=
[0]None, name=
[0]None, force=
[0]False)

10.2.61.3 Keyword Arguments

mol_id: The molecule identification string corresponding to one or more molecules.

name: The new molecule name.

force: A flag which if True will cause the molecule to be renamed.

10.2.61.4 Description

This function simply allows molecules to be named (or renamed).

10.2.61.5 Examples

To rename the molecule `Ap4Aase' to `Inhib Ap4Aase', type one of:


relax> molecule.
[0]
[0]name(
[0]
[0]`#Ap4Aase', `Inhib Ap4Aase', True)


relax> molecule.
[0]
[0]name(
[0]
[0]mol_id=
[0]
[0]`#Ap4Aase', name=
[0]
[0]`Inhib Ap4Aase', force=
[0]
[0]True)

This assumes the molecule `Ap4Aase' already exists.

10.2.61.6 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.






10.2.62 molecule.type()

10.2.62.1 Synopsis

Set the molecule type.

10.2.62.2 Defaults

molecule.
[0]type
(
[0]self, mol_id=
[0]None, type=
[0]None, force=
[0]False)

10.2.62.3 Keyword Arguments

mol_id: The molecule identification string corresponding to one or more molecules.

type: The molecule type.

force: A flag which if True will cause the molecule to type to be overwritten.

10.2.62.4 Description

This function allows the type of the molecule to be specified. It can be one of:

`protein'
`organic molecule',
`DNA/RNA hybrid',
`polydeoxyribonucleotide',
`polypeptide(D)',
`polypeptide(L)',
`polyribonucleotide',
`polysaccharide(D)',
`polysaccharide(L)',
`other'.

10.2.62.5 Examples

To set the molecule `Ap4Aase' to the `polypeptide(L)' type, type one of:


relax> molecule.
[0]
[0]type(
[0]
[0]`#Ap4Aase', `polypeptide(
[0]
[0]L)', True)


relax> molecule.
[0]
[0]type(
[0]
[0]mol_id=
[0]
[0]`#Ap4Aase', type=
[0]
[0]`polypeptide(
[0]
[0]L)', force=
[0]
[0]True)






10.2.63 molmol.clear_history()

10.2.63.1 Synopsis

Function for clearing the Molmol command history.

10.2.63.2 Defaults

molmol.
[0]
[0]clear_history
(
[0]self)






10.2.64 molmol.command()

10.2.64.1 Synopsis

Function for executing a user supplied Molmol command.

10.2.64.2 Defaults

molmol.
[0]
[0]command
(
[0]self, command=
[0]None)

10.2.64.3 Keyword Arguments

command: The Molmol command to execute.

10.2.64.4 Description

This user function allows you to pass Molmol commands to the program. This can be useful for automation or scripting.

10.2.64.5 Example

To reinitialise the Molmol instance:


relax> molmol.
[0]
[0]
[0]command(
[0]
[0]"InitAll yes")






10.2.65 molmol.macro_exec()

10.2.65.1 Synopsis

Function for executing Molmol macros.

10.2.65.2 Defaults

molmol.
[0]macro_exec
(
[0]self, data_type=
[0]None, style=
[0]`classic', colour_start=
[0]None, colour_end=
[0]None, colour_list=
[0]None)

10.2.65.3 Keyword Arguments

data_type: The data type to map to the structure.

style: The style of the macro.

colour_start: The starting colour, either an array or string, of the linear colour gradient.

colour_end: The ending colour, either an array or string, of the linear colour gradient.

colour_list: The list of colours to match the start and end strings.

10.2.65.4 Description

This function allows residues specific values to be mapped to a structure through Molmol macros. Currently only the `classic' style, which is described below, is available.

10.2.65.5 Colour

The values are coloured based on a linear colour gradient which is specified through the `colour_start' and `colour_end' arguments. These arguments can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, colour_start=`white' and colour_start=[1.0, 1.0, 1.0] both select the same colour. Leaving both arguments at None will select the default colour gradient which for each type of analysis is described below.

When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default Molmol colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the string. To explicitly select these lists, set the `colour_list' argument to either `molmol' or `x11'.

10.2.65.6 Examples

To map the order parameter values, $ S^2$ , onto the structure using the classic style, type:


relax> molmol.
[0]
[0]macro_exec(
[0]
[0]`S2')


relax> molmol.
[0]
[0]macro_exec(
[0]
[0]data_type=
[0]
[0]`S2')


relax> molmol.
[0]
[0]macro_exec(
[0]
[0]data_type=
[0]
[0]`S2', style=
[0]
[0]"classic")






10.2.66 molmol.ribbon()

10.2.66.1 Synopsis

Apply the Molmol ribbon style.

10.2.66.2 Defaults

molmol.
[0]ribbon
(
[0]self)

10.2.66.3 Description

This function applies the Molmol ribbon style which is equivalent to clicking on `ribbon' in the Molmol side menu. To do this, the following commands are executed:

CalcAtom `H'
CalcAtom `HN'
CalcSecondary
XMacStand ribbon.mac

10.2.66.4 Example

To apply the ribbon style to the PDB file loaded, type:


relax> molmol.
[0]
[0]ribbon(
[0]
[0])






10.2.67 molmol.tensor_pdb()

10.2.67.1 Synopsis

Function displaying the diffusion tensor PDB geometric object over the loaded PDB.

10.2.67.2 Defaults

molmol.
[0]tensor_pdb
(
[0]self, file=
[0]None)

10.2.67.3 Keyword Arguments

file: The name of the PDB file containing the tensor geometric object.

10.2.67.4 Description

In executing this user function, a PDB file must have previously been loaded , a geometric object or polygon representing the Brownian rotational diffusion tensor will be overlain with the loaded PDB file and displayed within Molmol. The PDB file containing the geometric object must be created using the complementary `pdb.create_diff_tensor_pdb()' user function.

To display the diffusion tensor, the multiple commands will be executed. To overlay the structure with the diffusion tensor, everything will be selected and reoriented and moved to their original PDB frame positions:

SelectAtom `'
SelectBond `'
SelectAngle `'
SelectDist `'
SelectPrim `'
RotateInit
MoveInit

Next the tensor PDB file is read in, selected, and the covalent bonds of the PDB CONECT records calculated:

ReadPdb file
SelectMol `@file'
CalcBond 1 1 1

Then only the atoms and bonds of the geometric object are selected and the `ball/stick' style applied:

SelectAtom `0'
SelectBond `0'
SelectAtom `:TNS'
SelectBond `:TNS'
XMacStand ball_stick.mac

The appearance is finally touched up:

RadiusAtom 1
SelectAtom `:TNS@C*'
RadiusAtom 1.5






10.2.68 molmol.view()

10.2.68.1 Synopsis

Function for viewing the collection of molecules extracted from the PDB file.

10.2.68.2 Defaults

molmol.
[0]view
(
[0]self)

10.2.68.3 Example


relax> molmol.
[0]
[0]view(
[0]
[0])


relax> molmol.
[0]
[0]view(
[0]
[0])






10.2.69 molmol.write()

10.2.69.1 Synopsis

Function for creating Molmol macros.

10.2.69.2 Defaults

molmol.
[0]write
(
[0]self, data_type=
[0]None, style=
[0]`classic', colour_start=
[0]None, colour_end=
[0]None, colour_list=
[0]None, file=
[0]None, dir=
[0]`molmol', force=
[0]False)

10.2.69.3 Keyword Arguments

data_type: The data type to map to the structure.

style: The style of the macro.

colour_start: The starting colour, either an array or string, of the linear colour gradient.

colour_end: The ending colour, either an array or string, of the linear colour gradient.

colour_list: The list of colours to match the start and end strings.

file: The name of the file.

dir: The directory name.

force: A flag which, if set to True, will cause the file to be overwritten.

10.2.69.4 Description

This function allows residues specific values to be mapped to a structure through the creation of a Molmol `*.mac' macro which can be executed in Molmol by clicking on `File, Macro, Execute User...'. Currently only the `classic' style, which is described below, is available.

10.2.69.5 Colour

The values are coloured based on a linear colour gradient which is specified through the `colour_start' and `colour_end' arguments. These arguments can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, colour_start=`white' and colour_start=[1.0, 1.0, 1.0] both select the same colour. Leaving both arguments at None will select the default colour gradient which for each type of analysis is described below.

When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default Molmol colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the string. To explicitly select these lists, set the `colour_list' argument to either `molmol' or `x11'.

10.2.69.6 Examples

To create a Molmol macro mapping the order parameter values, $ S^2$ , onto the structure using the classic style, type:


relax> molmol.
[0]
[0]write(
[0]
[0]`S2')


relax> molmol.
[0]
[0]write(
[0]
[0]data_type=
[0]
[0]`S2')


relax> molmol.
[0]
[0]write(
[0]
[0]data_type=
[0]
[0]`S2', style=
[0]
[0]"classic", file=
[0]
[0]`s2.
[0]
[0]mac', dir=
[0]
[0]`molmol')

10.2.69.7 Model-free classic style

Creator: Edward d'Auvergne

Argument string: "classic"

Description: The classic style draws the backbone of a protein in the Molmol `neon' style. Rather than colouring the amino acids to which the NH bond belongs, the three covalent bonds of the peptide bond from Ca to Ca in which the NH bond is located are coloured. Deselected residues are shown as black lines.

Supported data types:

(see table 10.17)

Table: First table for the molmol.write() user function.
Data type String Description
$ S^2$ . `S2' The standard model-free order parameter, equal to $ S^2_f$ .S2s
for the two timescale models. The default colour
gradient starts at `yellow' and ends at `red'.
$ S^2_f$ . `S2f' The order parameter of the faster of two internal
motions. Residues which are described by model-free
models m1 to m4, the single timescale models, are
illustrated as white neon bonds. The default colour
gradient is the same as that for the $ S^2$ data type.
$ S^2_s$ . `S2s' The order parameter of the slower of two internal
motions. This functions exactly as $ S^2_f$ except that $ S^2_s$
is plotted instead.
Amplitude of `amp_fast' Model independent display of the amplite of fast motions.
fast motions. For residues described by model-free models m5 to m8, the
value plotted is that of $ S^2_f$ . However, for residues
described by models m1 to m4, what is shown is dependent
on the timescale of the motions. This is because these
single timescale models can, at times, be perfect
approximations to the more complex two timescale models.
Hence if $ \tau _e$ is less than 200 ps, $ S^2$ is plotted. Otherwise
the peptide bond is coloured white. The default colour
gradient is the same as that for $ S^2$ .
Amplitude of `amp_slow' Model independent display of the amplite of slow motions,
slow motions. arbitrarily defined as motions slower than 200 ps. For
residues described by model-free models m5 to m8, the
order parameter $ S^2$ is plotted if $ \tau _s$ $ >$ 200 ps. For models
m1 to m4, $ S^2$ is plotted if $ \tau _e$ $ >$ 200 ps. The default
colour gradient is the same as that for $ S^2$ .
$ \tau _e$ . `te' The correlation time, $ \tau _e$ . The default colour gradient
starts at `turquoise' and ends at `blue'.
$ \tau _f$ . `tf' The correlation time, $ \tau _f$ . The default colour gradient is
the same as that of $ \tau _e$ .
$ \tau _s$ . `ts' The correlation time, $ \tau _s$ . The default colour gradient
starts at `blue' and ends at `black'.
Timescale of `time_fast' Model independent display of the timescale of fast
fast motions motions. For models m5 to m8, only the parameter $ \tau _f$ is
plotted. For models m2 and m4, the parameter $ \tau _e$ is
plotted only if it is less than 200 ps. All other
residues are assumed to have a correlation time of zero.
The default colour gradient is the same as that of $ \tau _e$ .
Timescale of `time_slow' Model independent display of the timescale of slow
slow motions motions. For models m5 to m8, only the parameter $ \tau _s$ is
plotted. For models m2 and m4, the parameter $ \tau _e$ is
plotted only if it is greater than 200 ps. All other
residues are coloured white. The default colour gradient
is the same as that of $ \tau _s$ .
Chemical `Rex' The chemical exchange, $ R_{ex}$ . Residues which experience no
exchange chemical exchange are coloured white. The default colour
gradient starts at `yellow' and finishes at `red'.


10.2.69.8 Molmol RGB colour arrays

The following table is a list of colours used in Molmol and their corresponding RGB colour values ranging from 0 to 1.

(see table 10.18)

Table: Second table for the molmol.write() user function.
Name Red Green Blue
`black' 0.000 0.000 0.000
`navy' 0.000 0.000 0.502
`blue' 0.000 0.000 1.000
`dark green' 0.000 0.392 0.000
`green' 0.000 1.000 0.000
`cyan' 0.000 1.000 1.000
`turquoise' 0.251 0.878 0.816
`royal blue' 0.255 0.412 0.882
`aquamarine' 0.498 1.000 0.831
`sky green' 0.529 0.808 0.922
`dark violet' 0.580 0.000 0.827
`pale green' 0.596 0.984 0.596
`purple' 0.627 0.125 0.941
`brown' 0.647 0.165 0.165
`light blue' 0.678 0.847 0.902
`grey' 0.745 0.745 0.745
`light grey' 0.827 0.827 0.827
`violet' 0.933 0.510 0.933
`light coral' 0.941 0.502 0.502
`khaki' 0.941 0.902 0.549
`beige' 0.961 0.961 0.863
`red' 1.000 0.000 0.000
`magenta' 1.000 0.000 1.000
`deep pink' 1.000 0.078 0.576
`orange red' 1.000 0.271 0.000
`hot pink' 1.000 0.412 0.706
`coral' 1.000 0.498 0.314
`dark orange' 1.000 0.549 0.000
`orange' 1.000 0.647 0.000
`pink' 1.000 0.753 0.796
`gold' 1.000 0.843 0.000
`yellow' 1.000 1.000 0.000
`light yellow' 1.000 1.000 0.878
`ivory' 1.000 1.000 0.941
`white' 1.000 1.000 1.000

10.2.69.9 X11 RGB colour arrays

The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.

(see table 10.19)

Table: Third table for the molmol.write() user function.

Name Red Green Blue

snow

255 250 250
ghost white 248 248 255
white smoke 245 245 245
gainsboro 220 220 220
floral white 255 250 240
old lace 253 245 230
linen 250 240 230
antique white 250 235 215
papaya whip 255 239 213
blanched almond 255 235 205
bisque 255 228 196
peach puff 255 218 185
navajo white 255 222 173
moccasin 255 228 181
cornsilk 255 248 220
ivory 255 255 240
lemon chiffon 255 250 205
seashell 255 245 238
honeydew 240 255 240
mint cream 245 255 250
azure 240 255 255
alice blue 240 248 255
lavender 230 230 250
lavender blush 255 240 245
misty rose 255 228 225
white 255 255 255
black 0 0 0
dark slate grey 47 79 79
dim grey 105 105 105
slate grey 112 128 144
light slate grey 119 136 153
grey 190 190 190
light grey 211 211 211
midnight blue 25 25 112
navy 0 0 128
cornflower blue 100 149 237
dark slate blue 72 61 139
slate blue 106 90 205
medium slate blue 123 104 238
light slate blue 132 112 255
medium blue 0 0 205
royal blue 65 105 225
blue 0 0 255
dodger blue 30 144 255
deep sky blue 0 191 255
sky blue 135 206 235
light sky blue 135 206 250
steel blue 70 130 180
light steel blue 176 196 222
light blue 173 216 230
powder blue 176 224 230
pale turquoise 175 238 238
dark turquoise 0 206 209
medium turquoise 72 209 204
turquoise 64 224 208
cyan 0 255 255
light cyan 224 255 255
cadet blue 95 158 160
medium aquamarine 102 205 170
aquamarine 127 255 212
dark green 0 100 0
dark olive green 85 107 47
dark sea green 143 188 143
sea green 46 139 87
medium sea green 60 179 113
light sea green 32 178 170
pale green 152 251 152
spring green 0 255 127
lawn green 124 252 0
green 0 255 0
chartreuse 127 255 0
medium spring green 0 250 154
green yellow 173 255 47
lime green 50 205 50
yellow green 154 205 50
forest green 34 139 34
olive drab 107 142 35
dark khaki 189 183 107
khaki 240 230 140
pale goldenrod 238 232 170
light goldenrod yellow 250 250 210
light yellow 255 255 224
yellow 255 255 0
gold 255 215 0
light goldenrod 238 221 130
goldenrod 218 165 32
dark goldenrod 184 134 11
rosy brown 188 143 143
indian red 205 92 92
saddle brown 139 69 19
sienna 160 82 45
peru 205 133 63
burlywood 222 184 135
beige 245 245 220
wheat 245 222 179
sandy brown 244 164 96
tan 210 180 140
chocolate 210 105 30
firebrick 178 34 34
brown 165 42 42
dark salmon 233 150 122
salmon 250 128 114
light salmon 255 160 122
orange 255 165 0
dark orange 255 140 0
coral 255 127 80
light coral 240 128 128
tomato 255 99 71
orange red 255 69 0
red 255 0 0
hot pink 255 105 180
deep pink 255 20 147
pink 255 192 203
light pink 255 182 193
pale violet red 219 112 147
maroon 176 48 96
medium violet red 199 21 133
violet red 208 32 144
magenta 255 0 255
violet 238 130 238
plum 221 160 221
orchid 218 112 214
medium orchid 186 85 211
dark orchid 153 50 204
dark violet 148 0 211
blue violet 138 43 226
purple 160 32 240
medium purple 147 112 219
thistle 216 191 216
snow 1 255 250 250
snow 2 238 233 233
snow 3 205 201 201
snow 4 139 137 137
seashell 1 255 245 238
seashell 2 238 229 222
seashell 3 205 197 191
seashell 4 139 134 130
antique white 1 255 239 219
antique white 2 238 223 204
antique white 3 205 192 176
antique white 4 139 131 120
bisque 1 255 228 196
bisque 2 238 213 183
bisque 3 205 183 158
bisque 4 139 125 107
peach puff 1 255 218 185
peach puff 2 238 203 173
peach puff 3 205 175 149
peach puff 4 139 119 101
navajo white 1 255 222 173
navajo white 2 238 207 161
navajo white 3 205 179 139
navajo white 4 139 121 94
lemon chiffon 1 255 250 205
lemon chiffon 2 238 233 191
lemon chiffon 3 205 201 165
lemon chiffon 4 139 137 112
cornsilk 1 255 248 220
cornsilk 2 238 232 205
cornsilk 3 205 200 177
cornsilk 4 139 136 120
ivory 1 255 255 240
ivory 2 238 238 224
ivory 3 205 205 193
ivory 4 139 139 131
honeydew 1 240 255 240
honeydew 2 224 238 224
honeydew 3 193 205 193
honeydew 4 131 139 131
lavender blush 1 255 240 245
lavender blush 2 238 224 229
lavender blush 3 205 193 197
lavender blush 4 139 131 134
misty rose 1 255 228 225
misty rose 2 238 213 210
misty rose 3 205 183 181
misty rose 4 139 125 123
azure 1 240 255 255
azure 2 224 238 238
azure 3 193 205 205
azure 4 131 139 139
slate blue 1 131 111 255
slate blue 2 122 103 238
slate blue 3 105 89 205
slate blue 4 71 60 139
royal blue 1 72 118 255
royal blue 2 67 110 238
royal blue 3 58 95 205
royal blue 4 39 64 139
blue 1 0 0 255
blue 2 0 0 238
blue 3 0 0 205
blue 4 0 0 139
dodger blue 1 30 144 255
dodger blue 2 28 134 238
dodger blue 3 24 116 205
dodger blue 4 16 78 139
steel blue 1 99 184 255
steel blue 2 92 172 238
steel blue 3 79 148 205
steel blue 4 54 100 139
deep sky blue 1 0 191 255
deep sky blue 2 0 178 238
deep sky blue 3 0 154 205
deep sky blue 4 0 104 139
sky blue 1 135 206 255
sky blue 2 126 192 238
sky blue 3 108 166 205
sky blue 4 74 112 139
light sky blue 1 176 226 255
light sky blue 2 164 211 238
light sky blue 3 141 182 205
light sky blue 4 96 123 139
slate grey 1 198 226 255
slate grey 2 185 211 238
slate grey 3 159 182 205
slate grey 4 108 123 139
light steel blue 1 202 225 255
light steel blue 2 188 210 238
light steel blue 3 162 181 205
light steel blue 4 110 123 139
light blue 1 191 239 255
light blue 2 178 223 238
light blue 3 154 192 205
light blue 4 104 131 139
light cyan 1 224 255 255
light cyan 2 209 238 238
light cyan 3 180 205 205
light cyan 4 122 139 139
pale turquoise 1 187 255 255
pale turquoise 2 174 238 238
pale turquoise 3 150 205 205
pale turquoise 4 102 139 139
cadet blue 1 152 245 255
cadet blue 2 142 229 238
cadet blue 3 122 197 205
cadet blue 4 83 134 139
turquoise 1 0 245 255
turquoise 2 0 229 238
turquoise 3 0 197 205
turquoise 4 0 134 139
cyan 1 0 255 255
cyan 2 0 238 238
cyan 3 0 205 205
cyan 4 0 139 139
dark slate grey 1 151 255 255
dark slate grey 2 141 238 238
dark slate grey 3 121 205 205
dark slate grey 4 82 139 139
aquamarine 1 127 255 212
aquamarine 2 118 238 198
aquamarine 3 102 205 170
aquamarine 4 69 139 116
dark sea green 1 193 255 193
dark sea green 2 180 238 180
dark sea green 3 155 205 155
dark sea green 4 105 139 105
sea green 1 84 255 159
sea green 2 78 238 148
sea green 3 67 205 128
sea green 4 46 139 87
pale green 1 154 255 154
pale green 2 144 238 144
pale green 3 124 205 124
pale green 4 84 139 84
spring green 1 0 255 127
spring green 2 0 238 118
spring green 3 0 205 102
spring green 4 0 139 69
green 1 0 255 0
green 2 0 238 0
green 3 0 205 0
green 4 0 139 0
chartreuse 1 127 255 0
chartreuse 2 118 238 0
chartreuse 3 102 205 0
chartreuse 4 69 139 0
olive drab 1 192 255 62
olive drab 2 179 238 58
olive drab 3 154 205 50
olive drab 4 105 139 34
dark olive green 1 202 255 112
dark olive green 2 188 238 104
dark olive green 3 162 205 90
dark olive green 4 110 139 61
khaki 1 255 246 143
khaki 2 238 230 133
khaki 3 205 198 115
khaki 4 139 134 78
light goldenrod 1 255 236 139
light goldenrod 2 238 220 130
light goldenrod 3 205 190 112
light goldenrod 4 139 129 76
light yellow 1 255 255 224
light yellow 2 238 238 209
light yellow 3 205 205 180
light yellow 4 139 139 122
yellow 1 255 255 0
yellow 2 238 238 0
yellow 3 205 205 0
yellow 4 139 139 0
gold 1 255 215 0
gold 2 238 201 0
gold 3 205 173 0
gold 4 139 117 0
goldenrod 1 255 193 37
goldenrod 2 238 180 34
goldenrod 3 205 155 29
goldenrod 4 139 105 20
dark goldenrod 1 255 185 15
dark goldenrod 2 238 173 14
dark goldenrod 3 205 149 12
dark goldenrod 4 139 101 8
rosy brown 1 255 193 193
rosy brown 2 238 180 180
rosy brown 3 205 155 155
rosy brown 4 139 105 105
indian red 1 255 106 106
indian red 2 238 99 99
indian red 3 205 85 85
indian red 4 139 58 58
sienna 1 255 130 71
sienna 2 238 121 66
sienna 3 205 104 57
sienna 4 139 71 38
burlywood 1 255 211 155
burlywood 2 238 197 145
burlywood 3 205 170 125
burlywood 4 139 115 85
wheat 1 255 231 186
wheat 2 238 216 174
wheat 3 205 186 150
wheat 4 139 126 102
tan 1 255 165 79
tan 2 238 154 73
tan 3 205 133 63
tan 4 139 90 43
chocolate 1 255 127 36
chocolate 2 238 118 33
chocolate 3 205 102 29
chocolate 4 139 69 19
firebrick 1 255 48 48
firebrick 2 238 44 44
firebrick 3 205 38 38
firebrick 4 139 26 26
brown 1 255 64 64
brown 2 238 59 59
brown 3 205 51 51
brown 4 139 35 35
salmon 1 255 140 105
salmon 2 238 130 98
salmon 3 205 112 84
salmon 4 139 76 57
light salmon 1 255 160 122
light salmon 2 238 149 114
light salmon 3 205 129 98
light salmon 4 139 87 66
orange 1 255 165 0
orange 2 238 154 0
orange 3 205 133 0
orange 4 139 90 0
dark orange 1 255 127 0
dark orange 2 238 118 0
dark orange 3 205 102 0
dark orange 4 139 69 0
coral 1 255 114 86
coral 2 238 106 80
coral 3 205 91 69
coral 4 139 62 47
tomato 1 255 99 71
tomato 2 238 92 66
tomato 3 205 79 57
tomato 4 139 54 38
orange red 1 255 69 0
orange red 2 238 64 0
orange red 3 205 55 0
orange red 4 139 37 0
red 1 255 0 0
red 2 238 0 0
red 3 205 0 0
red 4 139 0 0
deep pink 1 255 20 147
deep pink 2 238 18 137
deep pink 3 205 16 118
deep pink 4 139 10 80
hot pink 1 255 110 180
hot pink 2 238 106 167
hot pink 3 205 96 144
hot pink 4 139 58 98
pink 1 255 181 197
pink 2 238 169 184
pink 3 205 145 158
pink 4 139 99 108
light pink 1 255 174 185
light pink 2 238 162 173
light pink 3 205 140 149
light pink 4 139 95 101
pale violet red 1 255 130 171
pale violet red 2 238 121 159
pale violet red 3 205 104 137
pale violet red 4 139 71 93
maroon 1 255 52 179
maroon 2 238 48 167
maroon 3 205 41 144
maroon 4 139 28 98
violet red 1 255 62 150
violet red 2 238 58 140
violet red 3 205 50 120
violet red 4 139 34 82
magenta 1 255 0 255
magenta 2 238 0 238
magenta 3 205 0 205
magenta 4 139 0 139
orchid 1 255 131 250
orchid 2 238 122 233
orchid 3 205 105 201
orchid 4 139 71 137
plum 1 255 187 255
plum 2 238 174 238
plum 3 205 150 205
plum 4 139 102 139
medium orchid 1 224 102 255
medium orchid 2 209 95 238
medium orchid 3 180 82 205
medium orchid 4 122 55 139
dark orchid 1 191 62 255
dark orchid 2 178 58 238
dark orchid 3 154 50 205
dark orchid 4 104 34 139
purple 1 155 48 255
purple 2 145 44 238
purple 3 125 38 205
purple 4 85 26 139
medium purple 1 171 130 255
medium purple 2 159 121 238
medium purple 3 137 104 205
medium purple 4 93 71 139
thistle 1 255 225 255
thistle 2 238 210 238
thistle 3 205 181 205
thistle 4 139 123 139
grey 0 0 0 0
grey 1 3 3 3
grey 2 5 5 5
grey 3 8 8 8
grey 4 10 10 10
grey 5 13 13 13
grey 6 15 15 15
grey 7 18 18 18
grey 8 20 20 20
grey 9 23 23 23
grey 10 26 26 26
grey 11 28 28 28
grey 12 31 31 31
grey 13 33 33 33
grey 14 36 36 36
grey 15 38 38 38
grey 16 41 41 41
grey 17 43 43 43
grey 18 46 46 46
grey 19 48 48 48
grey 20 51 51 51
grey 21 54 54 54
grey 22 56 56 56
grey 23 59 59 59
grey 24 61 61 61
grey 25 64 64 64
grey 26 66 66 66
grey 27 69 69 69
grey 28 71 71 71
grey 29 74 74 74
grey 30 77 77 77
grey 31 79 79 79
grey 32 82 82 82
grey 33 84 84 84
grey 34 87 87 87
grey 35 89 89 89
grey 36 92 92 92
grey 37 94 94 94
grey 38 97 97 97
grey 39 99 99 99
grey 40 102 102 102
grey 41 105 105 105
grey 42 107 107 107
grey 43 110 110 110
grey 44 112 112 112
grey 45 115 115 115
grey 46 117 117 117
grey 47 120 120 120
grey 48 122 122 122
grey 49 125 125 125
grey 50 127 127 127
grey 51 130 130 130
grey 52 133 133 133
grey 53 135 135 135
grey 54 138 138 138
grey 55 140 140 140
grey 56 143 143 143
grey 57 145 145 145
grey 58 148 148 148
grey 59 150 150 150
grey 60 153 153 153
grey 61 156 156 156
grey 62 158 158 158
grey 63 161 161 161
grey 64 163 163 163
grey 65 166 166 166
grey 66 168 168 168
grey 67 171 171 171
grey 68 173 173 173
grey 69 176 176 176
grey 70 179 179 179
grey 71 181 181 181
grey 72 184 184 184
grey 73 186 186 186
grey 74 189 189 189
grey 75 191 191 191
grey 76 194 194 194
grey 77 196 196 196
grey 78 199 199 199
grey 79 201 201 201
grey 80 204 204 204
grey 81 207 207 207
grey 82 209 209 209
grey 83 212 212 212
grey 84 214 214 214
grey 85 217 217 217
grey 86 219 219 219
grey 87 222 222 222
grey 88 224 224 224
grey 89 227 227 227
grey 90 229 229 229
grey 91 232 232 232
grey 92 235 235 235
grey 93 237 237 237
grey 94 240 240 240
grey 95 242 242 242
grey 96 245 245 245
grey 97 247 247 247
grey 98 250 250 250
grey 99 252 252 252
grey 100 255 255 255
dark grey 169 169 169
dark blue 0 0 139
dark cyan 0 139 139
dark magenta 139 0 139
dark red 139 0 0
light green 144 238 144





10.2.70 monte_carlo.create_data()

10.2.70.1 Synopsis

Function for creating simulation data.

10.2.70.2 Defaults

monte_carlo.
[0]
[0]create_data
(
[0]self, method=
[0]`back_calc')

10.2.70.3 Keyword Arguments

method: The simulation method.

10.2.70.4 Description

The method argument can either be set to `back_calc' or `direct', the choice of which determines the simulation type. If the values or parameters are calculated rather than minimised, this option will have no effect, hence, `back_calc' and `direct' are identical.

For error analysis, the method argument should be set to `back_calc' which will result in proper Monte Carlo simulations. The data used for each simulation is back calculated from the minimised model parameters and is randomised using Gaussian noise where the standard deviation is from the original error set. When the method is set to `back_calc', this function should only be called after the model is fully minimised.

The simulation type can be changed by setting the method argument to `direct'. This will result in simulations which cannot be used in error analysis and which are no longer Monte Carlo simulations. However, these simulations are required for certain model selection techniques (see the documentation for the model selection function for details), and can be used for other purposes. Rather than the data being back calculated from the fitted model parameters, the data is generated by taking the original data and randomising using Gaussian noise with the standard deviations set to the original error set.

10.2.70.5 Monte Carlo Simulation Overview

For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:

1. The measured data set together with the corresponding error set should be loaded into relax.

2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.

3. To initialise and turn on Monte Carlo simulations, the number of simulations, $ n$ , needs to be set.

4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.

5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).

6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.

7. Failed simulations are removed using the techniques of model elimination.

8. The model parameter errors are calculated from the distribution of simulation parameters.

Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.

An example, for model-free analysis, which includes only the functions required for implementing the above steps is:


relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.


relax> minimise(
[0]
[0]`newton') # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.


relax> minimise(
[0]
[0]`newton') # Step 6.


relax> eliminate(
[0]
[0]) # Step 7.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.

An example for reduced spectral density mapping is:


relax> calc(
[0]
[0]) # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> calc(
[0]
[0]) # Step 6.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.





10.2.71 monte_carlo.error_analysis()

10.2.71.1 Synopsis

Function for calculating parameter errors from the Monte Carlo simulations.

10.2.71.2 Defaults

monte_carlo.
[0]
[0]error_analysis
(
[0]self, prune=
[0]0.0)

10.2.71.3 Keyword Arguments

prune: Legacy argument corresponding to `trim' in Art Palmer's Modelfree program.

10.2.71.4 Description

Parameter errors are calculated as the standard deviation of the distribution of parameter values. This function should never be used if parameter values are obtained by minimisation and the simulation data are generated using the method `direct'. The reason is because only true Monte Carlo simulations can give the true parameter errors.

The prune argument is legacy code which corresponds to the `trim' option in Art Palmer's Modelfree program. To remove failed simulations, the eliminate function should be used prior to this function. Eliminating the simulations specifically identifies and removes the failed simulations whereas the prune argument will only, in a few cases, positively identify failed simulations but only if severe parameter limits have been imposed. Most failed models will pass through the pruning process and hence cause a catastrophic increase in the parameter errors. If the argument must be used, the following must be taken into account. If the values or parameters are calculated rather than minimised, the prune argument must be set to zero. The value of this argument is proportional to the number of simulations removed prior to error calculation. If prune is set to 0.0, all simulations are used for calculating errors, whereas a value of 1.0 excludes all data. In almost all cases prune must be set to zero, any value greater than zero will result in an underestimation of the error values. If a value is supplied, the lower and upper tails of the distribution of chi-squared values will be excluded from the error calculation.

10.2.71.5 Monte Carlo Simulation Overview

For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:

1. The measured data set together with the corresponding error set should be loaded into relax.

2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.

3. To initialise and turn on Monte Carlo simulations, the number of simulations, $ n$ , needs to be set.

4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.

5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).

6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.

7. Failed simulations are removed using the techniques of model elimination.

8. The model parameter errors are calculated from the distribution of simulation parameters.

Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.

An example, for model-free analysis, which includes only the functions required for implementing the above steps is:


relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.


relax> minimise(
[0]
[0]`newton') # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.


relax> minimise(
[0]
[0]`newton') # Step 6.


relax> eliminate(
[0]
[0]) # Step 7.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.

An example for reduced spectral density mapping is:


relax> calc(
[0]
[0]) # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> calc(
[0]
[0]) # Step 6.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.





10.2.72 monte_carlo.initial_values()

10.2.72.1 Synopsis

Function for setting the initial simulation parameter values.

10.2.72.2 Defaults

monte_carlo.
[0]
[0]initial_values
(
[0]self)

10.2.72.3 Description

This function only effects where minimisation occurs and can therefore be skipped if the values or parameters are calculated rather than minimised. However, if accidentally run in this case, the results will be unaffected. It should only be called after the model or run is fully minimised. Once called, the functions `grid_search' and `minimise' will only effect the simulations and not the model parameters.

The initial values of the parameters for each simulation is set to the minimised parameters of the model. A grid search can be undertaken for each simulation instead, although this is computationally expensive and unnecessary. The minimisation function should be executed for a second time after running this function.

10.2.72.4 Monte Carlo Simulation Overview

For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:

1. The measured data set together with the corresponding error set should be loaded into relax.

2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.

3. To initialise and turn on Monte Carlo simulations, the number of simulations, $ n$ , needs to be set.

4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.

5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).

6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.

7. Failed simulations are removed using the techniques of model elimination.

8. The model parameter errors are calculated from the distribution of simulation parameters.

Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.

An example, for model-free analysis, which includes only the functions required for implementing the above steps is:


relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.


relax> minimise(
[0]
[0]`newton') # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.


relax> minimise(
[0]
[0]`newton') # Step 6.


relax> eliminate(
[0]
[0]) # Step 7.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.

An example for reduced spectral density mapping is:


relax> calc(
[0]
[0]) # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> calc(
[0]
[0]) # Step 6.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.





10.2.73 monte_carlo.off()

10.2.73.1 Synopsis

Function for turning simulations off.

10.2.73.2 Defaults

monte_carlo.
[0]off
(
[0]self)

10.2.73.3 Monte Carlo Simulation Overview

For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:

1. The measured data set together with the corresponding error set should be loaded into relax.

2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.

3. To initialise and turn on Monte Carlo simulations, the number of simulations, $ n$ , needs to be set.

4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.

5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).

6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.

7. Failed simulations are removed using the techniques of model elimination.

8. The model parameter errors are calculated from the distribution of simulation parameters.

Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.

An example, for model-free analysis, which includes only the functions required for implementing the above steps is:


relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.


relax> minimise(
[0]
[0]`newton') # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.


relax> minimise(
[0]
[0]`newton') # Step 6.


relax> eliminate(
[0]
[0]) # Step 7.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.

An example for reduced spectral density mapping is:


relax> calc(
[0]
[0]) # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> calc(
[0]
[0]) # Step 6.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.





10.2.74 monte_carlo.on()

10.2.74.1 Synopsis

Function for turning simulations on.

10.2.74.2 Defaults

monte_carlo.
[0]on
(
[0]self)

10.2.74.3 Monte Carlo Simulation Overview

For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:

1. The measured data set together with the corresponding error set should be loaded into relax.

2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.

3. To initialise and turn on Monte Carlo simulations, the number of simulations, $ n$ , needs to be set.

4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.

5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).

6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.

7. Failed simulations are removed using the techniques of model elimination.

8. The model parameter errors are calculated from the distribution of simulation parameters.

Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.

An example, for model-free analysis, which includes only the functions required for implementing the above steps is:


relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.


relax> minimise(
[0]
[0]`newton') # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.


relax> minimise(
[0]
[0]`newton') # Step 6.


relax> eliminate(
[0]
[0]) # Step 7.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.

An example for reduced spectral density mapping is:


relax> calc(
[0]
[0]) # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> calc(
[0]
[0]) # Step 6.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.





10.2.75 monte_carlo.setup()

10.2.75.1 Synopsis

Function for setting up Monte Carlo simulations.

10.2.75.2 Defaults

monte_carlo.
[0]setup
(
[0]self, number=
[0]500)

10.2.75.3 Keyword Arguments

number: The number of Monte Carlo simulations.

10.2.75.4 Description

This function must be called prior to any of the other Monte Carlo functions. The effect is that the number of simulations will be set and that simulations will be turned on.

10.2.75.5 Monte Carlo Simulation Overview

For proper error analysis using Monte Carlo simulations, a sequence of function calls is required for running the various simulation components. The steps necessary for implementing Monte Carlo simulations are:

1. The measured data set together with the corresponding error set should be loaded into relax.

2. Either minimisation is used to optimise the parameters of the chosen model, or a calculation is run.

3. To initialise and turn on Monte Carlo simulations, the number of simulations, $ n$ , needs to be set.

4. The simulation data needs to be created either by back calculation from the fully minimised model parameters from step 2 or by direct calculation when values are calculated rather than minimised. The error set is used to randomise each simulation data set by assuming Gaussian errors. This creates a synthetic data set for each Monte Carlo simulation.

5. Prior to minimisation of the parameters of each simulation, initial parameter estimates are required. These are taken as the optimised model parameters. An alternative is to use a grid search for each simulation to generate initial estimates, however this is extremely computationally expensive. For the case where values are calculated rather than minimised, this step should be skipped (although the results will be unaffected if this is accidentally run).

6. Each simulation requires minimisation or calculation. The same techniques as used in step 2, excluding the grid search when minimising, should be used for the simulations.

7. Failed simulations are removed using the techniques of model elimination.

8. The model parameter errors are calculated from the distribution of simulation parameters.

Monte Carlo simulations can be turned on or off using functions within this class. Once the function for setting up simulations has been called, simulations will be turned on. The effect of having simulations turned on is that the functions used for minimisation (grid search, minimise, etc) or calculation will only affect the simulation parameters and not the model parameters. By subsequently turning simulations off using the appropriate function, the functions used in minimisation will affect the model parameters and not the simulation parameters.

An example, for model-free analysis, which includes only the functions required for implementing the above steps is:


relax> grid_search(
[0]
[0]inc=
[0]
[0]11) # Step 2.


relax> minimise(
[0]
[0]`newton') # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> monte_carlo.
[0]
[0]
[0]initial_values(
[0]
[0]) # Step 5.


relax> minimise(
[0]
[0]`newton') # Step 6.


relax> eliminate(
[0]
[0]) # Step 7.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.

An example for reduced spectral density mapping is:


relax> calc(
[0]
[0]) # Step 2.


relax> monte_carlo.
[0]
[0]setup(
[0]
[0]number=
[0]
[0]500) # Step 3.


relax> monte_carlo.
[0]
[0]
[0]create_data(
[0]
[0]method=
[0]
[0]`back_calc') # Step 4.


relax> calc(
[0]
[0]) # Step 6.


relax> monte_carlo.
[0]
[0]
[0]error_analysis(
[0]
[0]) # Step 8.





10.2.76 n_state_model.CoM()

10.2.76.1 Synopsis

Centre of mass (CoM) analysis.

10.2.76.2 Defaults

n_state_model.
[0]CoM
(
[0]self, pivot_point=
[0][0.0, 0.0, 0.0], centre=
[0]None)

10.2.76.3 Keyword Arguments

pivot_point: The pivot point of the motions between the two domains.

centre: The optional argument for manually specifying the CoM of the initial position prior to the N rotations to the positions of the N states.

10.2.76.4 Description

This function is used for analysing the domain motion information content of the N states from the N-state model. The states do not correspond to physical states, hence nothing can be extracted from the individual states. This analysis involves the calculation of the pivot to centre of mass (pivot-CoM) order parameter and subsequent cone of motions.

For the analysis, both the pivot point and centre of mass must be specified. The supplied pivot point must be a vector of floating point numbers of length 3. If the centre keyword argument is supplied, it must also be a vector of floating point numbers (of length 3). If the centre argument is not supplied, then the CoM will be calulcated from the selected parts of a previously loaded structure.

10.2.76.5 Examples

To perform an analysis where the pivot is at the origin and the CoM is set to the N-terminal domain of a previously loaded PDB file (the C-terminal domain has been deselected), type:


relax> n_state_model.
[0]
[0]CoM(
[0]
[0])

To perform an analysis where the pivot is at the origin (because the real pivot has been shifted to this position) and the CoM is at the position [0, 0, 1], type one of:


relax> n_state_model.
[0]
[0]CoM(
[0]
[0]centre=
[0]
[0][0, 0, 1])


relax> n_state_model.
[0]
[0]CoM(
[0]
[0]centre=
[0]
[0][0.0, 0.0, 1.0])


relax> n_state_model.
[0]
[0]CoM(
[0]
[0]pivot_point=
[0]
[0][0.0, 0.0, 0.0], centre=
[0]
[0][0.0, 0.0, 1.0])





10.2.77 n_state_model.cone_pdb()

10.2.77.1 Synopsis

Create a PDB file representing the cone models from the centre of mass (CoM) analysis.

10.2.77.2 Defaults

n_state_model.
[0]
[0]cone_pdb
(
[0]self, cone_type=
[0]None, scale=
[0]1.0, file=
[0]`cone.
[0]pdb', dir=
[0]None, force=
[0]False)

10.2.77.3 Keyword Arguments

cone_type: The type of cone model to represent.

scale: Value for scaling the pivot-CoM distance which the size of the cone defaults to.

file: The name of the PDB file.

dir: The directory where the file is located.

force: A flag which, if set to True, will overwrite the any pre-existing file.

10.2.77.4 Description

This function creates a PDB file containing an artificial geometric structure to represent the various cone models. These models include:

`diff in cone'
`diff on cone'

The model can be selected by setting the cone_type argument to one of these strings. The cone is represented as an isotropic cone with its axis parallel to the average pivot-CoM vector, the vertex placed at the pivot point of the domain motions, and the length of the edge of the cone equal to the pivot-CoM distance multipled by the scaling argument. The resultant PDB file can subsequently read into any molecular viewer.

There are four different types of residue within the PDB. The pivot point is represented as as a single carbon atom of the residue `PIV'. The cone consists of numerous H atoms of the residue `CON'. The average pivot-CoM vector is presented as the residue `AVE' with one carbon atom positioned at the pivot and the other at the head of the vector (after scaling by the scale argument). Finally, if Monte Carlo have been performed, there will be multiple `MCC' residues representing the cone for each simulation, and multiple `MCA' residues representing the varying average pivot-CoM vector for each simulation.

To create the diffusion in a cone PDB representation, a uniform distribution of vectors on a sphere is generated using spherical coordinates with the polar angle defined from the average pivot-CoM vector. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These are all placed into the PDB file as H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines representing the filled cone.





10.2.78 n_state_model.elim_no_prob()

10.2.78.1 Synopsis

Eliminate the structures or states with no probability.

10.2.78.2 Defaults

n_state_model.
[0]
[0]elim_no_prob
(
[0]self)

10.2.78.3 Examples

Simply type:


relax> n_state_model.
[0]
[0]
[0]elim_no_prob(
[0]
[0]N=
[0]
[0]8)





10.2.79 n_state_model.number_of_states()

10.2.79.1 Synopsis

Set the number of states in the N-state model.

10.2.79.2 Defaults

n_state_model.
[0]number_of_states
(
[0]self, N=
[0]None)

10.2.79.3 Keyword Arguments

N: The number of states.

10.2.79.4 Description

Prior to optimisation, the number of states in the N-state model can be specified. If the number of states is not set, then this parameter will be equal to the number of loaded structures.

10.2.79.5 Examples

To set up an 8-state model, type:


relax> n_state_model.
[0]
[0]number_of_states(
[0]
[0]N=
[0]
[0]8)





10.2.80 n_state_model.ref_domain()

10.2.80.1 Synopsis

Set the reference domain for the `2-domain' N-state model.

10.2.80.2 Defaults

n_state_model.
[0]ref_domain
(
[0]self, ref=
[0]None)

10.2.80.3 Keyword Arguments

ref: The domain which will act as the frame of reference. This is only valid for the `2-domain' N-state model.

10.2.80.4 Description

Prior to optimisation of the `2-domain' N-state model, which of the two domains will act as the frame of reference must be specified. The N-states will be rotations of the other domain, so to switch the frame of reference to the other domain simply transpose the rotation matrices.

10.2.80.5 Examples

To set up a 5-state model with `C' domain being the frame of reference, type:


relax> n_state_model.
[0]
[0]ref_domain(
[0]
[0]ref=
[0]
[0]`C')





10.2.81 n_state_model.select_model()

10.2.81.1 Synopsis

Select the N-state model type and set up the model.

10.2.81.2 Defaults

n_state_model.
[0]select_model
(
[0]self, model=
[0]None)

10.2.81.3 Keyword Arguments

model: The name of the preset N-state model.

10.2.81.4 Description

Prior to optimisation, the N-state model type should be selected. The preset models are:

`2-domain' - The N-state model for a system of two domains, where one domain experiences a a reduced tensor.

`population' - The N-state model whereby only populations are optimised. The structures loaded into relax are assumed to be fixed. I.e. if two domains are present, the Euler angles for each state are fixed. The parameters of the model include the weight or probability for each state and the alignment tensor - {p0, p1, ..., pN, Axx, Ayy, Axy, Axz, Ayz}.

`fixed' - The N-state model whereby all motions are fixed and all populations are fixed to the set probabilities. The parameters of the model are simply the alignment tensor, {Axx, Ayy, Axy, Axz, Ayz}.

10.2.81.5 Examples

To analyse populations of states, type:


relax> n_state_model.
[0]
[0]select_model(
[0]
[0]model=
[0]
[0]`populations')





10.2.82 noe.read_restraints()

10.2.82.1 Synopsis

Read NOESY or ROESY restraints from a file.

10.2.82.2 Defaults

noe.
[0]read_restraints
(
[0]self, file=
[0]None, dir=
[0]None, proton1_col=
[0]None, proton2_col=
[0]None, lower_col=
[0]None, upper_col=
[0]None, sep=
[0]None)

10.2.82.3 Keyword Arguments

file: The name of the file containing the relaxation data.

dir: The directory where the file is located.

proton1_col: The column containing the first proton of the NOE or ROE cross peak.

proton2_col: The column containing the second proton of the NOE or ROE cross peak.

lower_col: The column containing the lower NOE bound.

upper_col: The column containing the upper NOE bound.

sep: The column separator (the default is white space).

10.2.82.4 Description

This function can automatically determine the format of the file, for example Xplor formatted restraint files. A generically formatted file is also supported if it contains minimally four columns with the two proton names and the upper and lower bounds, as specified by the *_col arguments. The proton names need to be in the spin identification string format.

10.2.82.5 Examples

To read the Xplor formatted restraint file `NOE.xpl', type one of:


relax> noe.
[0]
[0]read_restraints(
[0]
[0]`NOE.
[0]
[0]xpl')


relax> noe.
[0]
[0]read_restraints(
[0]
[0]file=
[0]
[0]`NOE.
[0]
[0]xpl')

To read the generic formatted file `noes', type one of:


relax> noe.
[0]
[0]read_restraints(
[0]
[0]file=
[0]
[0]`NOE.
[0]
[0]xpl', proton1_col=
[0]
[0]0, proton2_col=
[0]
[0]1, lower_col=
[0]
[0]2, upper_col=
[0]
[0]3)





10.2.83 noe.spectrum_type()

10.2.83.1 Synopsis

Set the steady-state NOE spectrum type for pre-loaded peak intensities.

10.2.83.2 Defaults

noe.
[0]spectrum_type
(
[0]self, spectrum_type=
[0]None, spectrum_id=
[0]None)

10.2.83.3 Keyword Arguments

spectrum_type: The type of steady-state NOE spectrum, one of `ref' or `sat'.

spectrum_id: The spectrum identification string.

10.2.83.4 Description

The spectrum_type argument can have the following values:

`ref' -
The steady-state NOE reference spectrum.
`sat' -
The steady-state NOE spectrum with proton saturation turned on.

Peak intensities should be loaded before calling this user function via the `spectrum.read_intensities()' user function. The intensity values will then be associated with a spectrum identifier which can be used here.





10.2.84 palmer.create()

10.2.84.1 Synopsis

Function for creating the Modelfree4 input files.

10.2.84.2 Defaults

palmer.
[0]
[0]create
(
[0]self, dir=
[0]None, force=
[0]False, binary=
[0]`modelfree4', diff_search=
[0]`none', sims=
[0]0, sim_type=
[0]`pred', trim=
[0]0, steps=
[0]20, constraints=
[0]True, heteronuc_type=
[0]`15N', atom1=
[0]`N', atom2=
[0]`H', spin_id=
[0]None)

10.2.84.3 Keyword Arguments

dir: The directory to place the files.

force: A flag which if set to True will cause the results file to be overwritten if it already exists.

binary: The name of the executable Modelfree program file.

diff_search: See the Modelfree4 manual for `diffusion_search'.

sims: The number of Monte Carlo simulations.

sim_type: See the Modelfree4 manual.

trim: See the Modelfree4 manual.

steps: See the Modelfree4 manual.

constraints: A flag specifying whether the parameters should be constrained. The default is to turn constraints on (constraints=True).

heteronuc_type: A three letter string describing the heteronucleus type, ie 15N, 13C, etc.

atom1: The symbol of the X heteronucleus in the pdb file.

atom2: The symbol of the H nucleus in the pdb file.

spin_id: The spin identification string.

10.2.84.4 Description

The following files are created

`dir/mfin',
`dir/mfdata',
`dir/mfpar',
`dir/mfmodel',
`dir/run.sh'.

The file `dir/run.sh' contains the single command,

`modelfree4 -i mfin -d mfdata -p mfpar -m mfmodel -o mfout -e out',

which can be used to execute modelfree4.

If you would like to use a different Modelfree executable file, change the keyword argument `binary' to the appropriate file name. If the file is not located within the environment's path, include the full path infront of the binary file name.





10.2.85 palmer.execute()

10.2.85.1 Synopsis

Function for executing Modelfree4.

10.2.85.2 Defaults

palmer.
[0]
[0]execute
(
[0]self, dir=
[0]None, force=
[0]False, binary=
[0]`modelfree4')

10.2.85.3 Keyword Arguments

dir: The directory to place the files.

force: A flag which if set to True will cause the results file to be overwritten if it already exists.

binary: The name of the executable Modelfree program file.

10.2.85.4 Description

Modelfree 4 will be executed as


$ modelfree4 -i mfin -d mfdata -p mfpar -m mfmodel -o mfout -e out

If a PDB file is loaded and non-isotropic diffusion is selected, then the file name will be placed on the command line as `-s pdb_file_name'.

If you would like to use a different Modelfree executable file, change the keyword argument `binary' to the appropriate file name. If the file is not located within the environment's path, include the full path in front of the binary file name.





10.2.86 palmer.extract()

10.2.86.1 Synopsis

Function for extracting data from the Modelfree4 `mfout' star formatted file.

10.2.86.2 Defaults

palmer.
[0]
[0]extract
(
[0]self, dir=
[0]None)

10.2.86.3 Keyword Arguments

dir: The directory where the file `mfout' is found.





10.2.87 paramag.centre()

10.2.87.1 Synopsis

Specify which atom is the paramagnetic centre.

10.2.87.2 Defaults

paramag.
[0]
[0]centre
(
[0]self, pos=
[0]None, atom_id=
[0]None, pipe=
[0]None, verbosity=
[0]1, fix=
[0]True, ave_pos=
[0]True, force=
[0]False)

10.2.87.3 Keyword Arguments

pos: The atomic position.

atom_id: The atom ID string.

pipe: The data pipe containing the structures to extract the centre from.

verbosity: The amount of information to print out.

fix: A flag specifying if the paramagnetic centre should be fixed during optimisation.

ave_pos: A flag specifying if the position of the atom is to be averaged across all models.

force: A flag which if True will cause the current paramagnetic centre to be overwritten.

10.2.87.4 Description

This function is required for specifying where the paramagnetic centre is located in the loaded structure file. If no structure number is given, then the average atom position will be calculated if multiple structures are loaded.

A different set of structures than those loaded into the current data pipe can also be used to determine the position, or its average. This can be achieved by loading the alternative structures into another data pipe, and then specifying that pipe through the pipe argument.

If the ave_pos flag is set to True, the average position from all models will be used as the position of the paramagnetic centre. If False, then the positions from all structures will be used. If multiple positions are used, then a fast paramagnetic centre motion will be assumed so that PCSs for a single tensor will be calculated for each position, and the PCS values linearly averaged.

10.2.87.5 Examples

If the paramagnetic centre is the lanthanide Dysprosium which is labelled as $ \mathfrak{D}_y$ in a loaded PDB file, then type one of:


relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]`Dy')


relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]atom_id=
[0]
[0]`Dy')

If the carbon atom `C1' of residue `4' in the PDB file is to be used as the paramagnetic centre, then type:


relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]`:4@C1')

To state that the Dy3+ atomic position is [0.136, 12.543, 4.356], type one of:


relax> paramag.
[0]
[0]
[0]centre(
[0]
[0][0.136, 12.543, 4.356])


relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]pos=
[0]
[0][0.136, 12.543, 4.356])

To find an unknown paramagnetic centre, type:


relax> paramag.
[0]
[0]
[0]centre(
[0]
[0]fix=
[0]
[0]False)





10.2.88 pcs.back_calc()

10.2.88.1 Synopsis

Back calculate the pseudo-contact shifts.

10.2.88.2 Defaults

pcs.
[0]
[0]back_calc
(
[0]self, align_id=
[0]None)

10.2.88.3 Keyword Arguments

align_id: The alignment ID string.





10.2.89 pcs.calc_q_factors()

10.2.89.1 Synopsis

Calculate the PCS Q-factor for the selected spins.

10.2.89.2 Defaults

pcs.
[0]
[0]calc_q_factors
(
[0]self, spin_id=
[0]None)

10.2.89.3 Keyword Arguments

spin_id: The spin ID string for restricting to subset of all selected spins.

10.2.89.4 Description

For this function to work, the back-calculated PCS data must first be generated by the analysis specific code. Otherwise a warning will be given.

10.2.89.5 Examples

To calculate the PCS Q-factor for only the spins `@H26', `@H27', and `@H28', type one of:


relax> pcs.
[0]
[0]
[0]calc_q_factors(
[0]
[0]`@H26 & @H27 & @H28')


relax> pcs.
[0]
[0]
[0]calc_q_factors(
[0]
[0]spin_id=
[0]
[0]`@H26 & @H27 & @H28')





10.2.90 pcs.copy()

10.2.90.1 Synopsis

Copy PCS data from pipe_from to pipe_to.

10.2.90.2 Defaults

pcs.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, pipe_to=
[0]None, align_id=
[0]None)

10.2.90.3 Keyword Arguments

pipe_from: The name of the pipe to copy the PCS data from.

pipe_to: The name of the pipe to copy the PCS data to.

align_id: The alignment ID string.

10.2.90.4 Description

This function will copy PCS data from `pipe_from' to `pipe_to'. If align_id is not given then all PCS data will be copied, otherwise only a specific data set will be.

10.2.90.5 Examples

To copy all PCS data from pipe `m1' to pipe `m9', type one of:


relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9')


relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9')


relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9', None)


relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9', align_id=
[0]
[0]None)

To copy only the `Th' PCS data from `m3' to `m6', type one of:


relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]`m3', `m6', `Th')


relax> pcs.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m3', pipe_to=
[0]
[0]`m6', align_id=
[0]
[0]`Th')





10.2.91 pcs.corr_plot()

10.2.91.1 Synopsis

Generate a correlation plot of the measured vs. the back-calculated PCSs.

10.2.91.2 Defaults

pcs.
[0]
[0]corr_plot
(
[0]self, format=
[0]`grace', file=
[0]`pcs_corr_plot.
[0]
[0]agr', dir=
[0]None, force=
[0]False)

10.2.91.3 Keyword Arguments

format: The format of the plot data.

file: The name of the file.

dir: The directory name.

force: A flag which if True will cause the file to be overwritten.

10.2.91.4 Description

Two formats are currently supported. If format is set to `grace', then a Grace plot file will be created. If the format arg is set to None, then a plain text list of the measured and back-calculated data will be created.

10.2.91.5 Examples

To create a Grace plot of the data, type:


relax> pcs.
[0]
[0]
[0]corr_plot(
[0]
[0])

To create a plain text list of the measured and back-calculated data, type one of:


relax> pcs.
[0]
[0]
[0]corr_plot(
[0]
[0]None)


relax> pcs.
[0]
[0]
[0]corr_plot(
[0]
[0]format=
[0]
[0]None)





10.2.92 pcs.delete()

10.2.92.1 Synopsis

Delete the PCS data corresponding to the alignment ID.

10.2.92.2 Defaults

pcs.
[0]
[0]delete
(
[0]self, align_id=
[0]None)

10.2.92.3 Keyword Arguments

align_id: The alignment ID string.

10.2.92.4 Examples

To delete the PCS data corresponding to align_id=`PH_gel', type:


relax> pcs.
[0]
[0]
[0]delete(
[0]
[0]`PH_gel')





10.2.93 pcs.display()

10.2.93.1 Synopsis

Display the PCS data corresponding to the alignment ID.

10.2.93.2 Defaults

pcs.
[0]
[0]display
(
[0]self, align_id=
[0]None)

10.2.93.3 Keyword Arguments

align_id: The alignment ID string.

10.2.93.4 Examples

To display the `phage' PCS data, type:


relax> pcs.
[0]
[0]
[0]display(
[0]
[0]`phage')





10.2.94 pcs.read()

10.2.94.1 Synopsis

Read the PCS data from file.

10.2.94.2 Defaults

pcs.
[0]read
(
[0]self, align_id=
[0]None, file=
[0]None, dir=
[0]None, spin_id_col=
[0]None, mol_name_col=
[0]None, res_num_col=
[0]None, res_name_col=
[0]None, spin_num_col=
[0]None, spin_name_col=
[0]None, data_col=
[0]None, error_col=
[0]None, sep=
[0]None, spin_id=
[0]None)

10.2.94.3 Keyword Arguments

align_id: The alignment ID string.

file: The name of the file containing the PCS data.

dir: The directory where the file is located.

spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).

mol_name_col: The molecule name column (alternative to the spin_id_col).

res_num_col: The residue number column (alternative to the spin_id_col).

res_name_col: The residue name column (alternative to the spin_id_col).

spin_num_col: The spin number column (alternative to the spin_id_col).

spin_name_col: The spin name column (alternative to the spin_id_col).

data_col: The PCS data column.

error_col: The experimental error column.

sep: The column separator (the default is white space).

spin_id: The spin ID string to restrict the loading of data to certain spin subsets.

10.2.94.4 Description

The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.

10.2.94.5 Examples

The following commands will read the PCS data out of the file `Tb.txt' where the columns are separated by the symbol `,', and store the PCSs under the ID `Tb'.


relax> pcs.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', sep=
[0]
[0]`,')

To read the 15N and 1H PCSs from the file `Eu.txt', where the 15N values are in the 4 $ ^\mathrm{th}$ column and the 1H in the 9 $ ^\mathrm{th}$ , type both the following:


relax> pcs.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', spin_id=
[0]
[0]`@N', res_num_col=
[0]
[0]1, data_col=
[0]
[0]4)


relax> pcs.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', spin_id=
[0]
[0]`@H', res_num_col=
[0]
[0]1, data_col=
[0]
[0]9)





10.2.95 pcs.weight()

10.2.95.1 Synopsis

Set optimisation weights on the PCS data.

10.2.95.2 Defaults

pcs.
[0]weight
(
[0]self, align_id=
[0]None, spin_id=
[0]None, weight=
[0]1.0)

10.2.95.3 Keyword Arguments

align_id: The alignment ID string.

spin_id: The spin ID string.

weight: The weighting value.

10.2.95.4 Description

This function can be used to force the PCS to contribute more or less to the chi-squared optimisation statistic. The higher the value, the more importance the PCS will have.





10.2.96 pcs.write()

10.2.96.1 Synopsis

Write the PCS data to file.

10.2.96.2 Defaults

pcs.
[0]write
(
[0]self, align_id=
[0]None, file=
[0]None, dir=
[0]None, force=
[0]False)

10.2.96.3 Keyword Arguments

align_id: The alignment ID string.

file: The name of the file.

dir: The directory name.

force: A flag which if True will cause the file to be overwritten.

10.2.96.4 Description

If no directory name is given, the file will be placed in the current working directory. The `align_id' argument are required for selecting which PCS data set will be written to file.





10.2.97 pdc.read()

10.2.97.1 Synopsis

Read the Bruker Protein Dynamics Centre (PDC) file.

10.2.97.2 Defaults

pdc.
[0]read
(
[0]self, ri_id=
[0]None, file=
[0]None, dir=
[0]None)

10.2.97.3 Keyword Arguments

ri_id: The relaxation data ID string.

file: The name of the PDC file.

dir: The directory where the file is located.

10.2.97.4 Description

This user function is used to load all of the data out of a Bruker PDC file for subsequent analysis within relax.





10.2.98 pipe.copy()

10.2.98.1 Synopsis

Function for copying a data pipe.

10.2.98.2 Defaults

pipe.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, pipe_to=
[0]None)

10.2.98.3 Keyword Arguments

pipe_from: The name of the source data pipe to copy the data from.

pipe_to: The name of the target data pipe to copy the data to.

10.2.98.4 Description

This user function allows the contents of a data pipe to be copied. If the `pipe_from' keyword argument is set to None the current data pipe is assumed. The data pipe corresponding to `pipe_to' must not yet exist.

10.2.98.5 Examples

To copy the contents of the `m1' data pipe to the `m2' data pipe, type:


relax> pipe.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2')


relax> pipe.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m2')

If the current data pipe is `m1', then the following command can be used:


relax> pipe.
[0]
[0]
[0]copy(
[0]
[0]pipe_to=
[0]
[0]`m2')





10.2.99 pipe.create()

10.2.99.1 Synopsis

Function for initialising a data pipe.

10.2.99.2 Defaults

pipe.
[0]
[0]create
(
[0]self, pipe_name=
[0]None, pipe_type=
[0]None)

10.2.99.3 Keyword Arguments

pipe_name: The name of the data pipe.

pipe_type: The type of data pipe.

10.2.99.4 Description

The data pipe name can be any string however the data pipe type can only be one of the following:

`frame order' -
The Frame Order theories,
`jw' -
Reduced spectral density mapping,
`mf' -
Model-free analysis,
`N-state' -
N-state model of domain motions,
`noe' -
Steady state NOE calculation,
`relax_fit' -
Relaxation curve fitting,

10.2.99.5 Examples

To set up a model-free analysis data pipe with the name `m5', type:


relax> pipe.
[0]
[0]
[0]create(
[0]
[0]`m5', `mf')





10.2.100 pipe.current()

10.2.100.1 Synopsis

Print the name of the current pipe.

10.2.100.2 Defaults

pipe.
[0]
[0]current
(
[0]self)

10.2.100.3 Examples

To run the user function, type:


relax> pipe.
[0]
[0]
[0]current(
[0]
[0])





10.2.101 pipe.delete()

10.2.101.1 Synopsis

Function for deleting a data pipe.

10.2.101.2 Defaults

pipe.
[0]
[0]delete
(
[0]self, pipe_name=
[0]None)

10.2.101.3 Keyword Arguments

pipe_name: The name of the data pipe.

10.2.101.4 Description

This function will permanently remove the data pipe and all of its contents. If the pipe name is not given, then all data pipes will be deleted.





10.2.102 pipe.display()

10.2.102.1 Synopsis

Print a list of all the data pipes.

10.2.102.2 Defaults

pipe.
[0]
[0]display
(
[0]self)

10.2.102.3 Examples

To run the user function, type:


relax> pipe.
[0]
[0]
[0]display(
[0]
[0])





10.2.103 pipe.hybridise()

10.2.103.1 Synopsis

Create a hybrid data pipe by fusing a number of other data pipes.

10.2.103.2 Defaults

pipe.
[0]
[0]hybridise
(
[0]self, hybrid=
[0]None, pipes=
[0]None)

10.2.103.3 Keyword Arguments

hybrid: The name of the hybrid data pipe to create.

pipes: An array containing the names of all data pipes to hybridise.

10.2.103.4 Description

This user function can be used to construct hybrid models. An example of the use of a hybrid model could be if the protein consists of two independent domains. These two domains could be analysed separately, each having their own optimised diffusion tensors. The N-terminal domain data pipe could be called `N_sphere' while the C-terminal domain could be called `C_ellipsoid'. These two data pipes could then be hybridised into a single data pipe called `mixed model' by typing:


relax> pipe.
[0]
[0]
[0]hybridise(
[0]
[0]`mixed model', [`N_sphere', `C_ellipsoid'])


relax> pipe.
[0]
[0]
[0]hybridise(
[0]
[0]hybrid=
[0]
[0]`mixed model', pipes=
[0]
[0][`N_sphere', `C_ellipsoid'])

This hybrid data pipe can then be compared via model selection to a data pipe whereby the entire protein is assumed to have a single diffusion tensor.

The requirements for data pipes to be hybridised is that the molecules, sequences, and spin systems for all the data pipes is the same, and that no spin system is allowed to be selected in two or more data pipes. The selections must not overlap to allow for rigorous statistical comparisons.





10.2.104 pipe.switch()

10.2.104.1 Synopsis

Function for switching between data pipes.

10.2.104.2 Defaults

pipe.
[0]switch
(
[0]self, pipe_name=
[0]None)

10.2.104.3 Keyword Arguments

pipe_name: The name of the data pipe.

10.2.104.4 Description

This function will switch from the current data pipe to the given data pipe.

10.2.104.5 Examples

To switch to the `ellipsoid' data pipe, type:


relax> pipe.
[0]
[0]switch(
[0]
[0]`ellipsoid')


relax> pipe.
[0]
[0]switch(
[0]
[0]pipe_name=
[0]
[0]`ellipsoid')





10.2.105 pymol.cartoon()

10.2.105.1 Synopsis

Apply the PyMOL cartoon style and colour by secondary structure.

10.2.105.2 Defaults

pymol.
[0]
[0]cartoon
(
[0]self)

10.2.105.3 Description

This function applies the PyMOL cartoon style which is equivalent to hiding everything and clicking on show cartoon. It also colours the cartoon with red helices, yellow strands, and green loops. The following commands are executed:

cmd.hide(`everything', file)
cmd.show(`cartoon', file)
util.cbss(file, `red', `yellow', `green')

where file is the file name without the `.pdb' extension.

10.2.105.4 Example

To apply this user function, type:


relax> pymol.
[0]
[0]
[0]cartoon(
[0]
[0])





10.2.106 pymol.clear_history()

10.2.106.1 Synopsis

Function for clearing the PyMOL command history.

10.2.106.2 Defaults

pymol.
[0]
[0]clear_history
(
[0]self)





10.2.107 pymol.command()

10.2.107.1 Synopsis

Function for executing a user supplied PyMOL command.

10.2.107.2 Defaults

pymol.
[0]
[0]command
(
[0]self, command=
[0]None)

10.2.107.3 Keyword Arguments

command: The PyMOL command to execute.

10.2.107.4 Description

This user function allows you to pass PyMOL commands to the program. This can be useful for automation or scripting.

10.2.107.5 Example

To reinitialise the PyMOL instance, type:


relax> pymol.
[0]
[0]
[0]command(
[0]
[0]"reinitialise")





10.2.108 pymol.cone_pdb()

10.2.108.1 Synopsis

Display, as designed, the cone PDB geometric object from the N-state model.

10.2.108.2 Defaults

pymol.
[0]
[0]cone_pdb
(
[0]self, file=
[0]None)

10.2.108.3 Keyword Arguments

file: The name of the PDB file containing the cone geometric object.

10.2.108.4 Description

The PDB file containing the geometric object must be created using the complementary `n_state_model.cone_pdb()' user function.

The cone PDB file is read in using the command:

load file

The average CoM-pivot point vector, the residue `AVE' is displayed using the commands:

select resn AVE
show sticks, `sele'
color blue, `sele'

The cone object, the residue `CON', is displayed using the commands:

select resn CON
hide (`sele')
show sticks, `sele'
color white, `sele'





10.2.109 pymol.macro_exec()

10.2.109.1 Synopsis

Function for executing PyMOL macros.

10.2.109.2 Defaults

pymol.
[0]macro_exec
(
[0]self, data_type=
[0]None, style=
[0]`classic', colour_start=
[0]None, colour_end=
[0]None, colour_list=
[0]None)

10.2.109.3 Keyword Arguments

data_type: The data type to map to the structure.

style: The style of the macro.

colour_start: The starting colour, either an array or string, of the linear colour gradient.

colour_end: The ending colour, either an array or string, of the linear colour gradient.

colour_list: The list of colours to match the start and end strings.

10.2.109.4 Description

This function allows residues specific values to be mapped to a structure through PyMOL macros. Currently only the `classic' style, which is described below, is available.

10.2.109.5 Colour

The values are coloured based on a linear colour gradient which is specified through the `colour_start' and `colour_end' arguments. These arguments can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, colour_start=`white' and colour_start=[1.0, 1.0, 1.0] both select the same colour. Leaving both arguments at None will select the default colour gradient which for each type of analysis is described below.

When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default PyMOL colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the Molmol list and then the X11 colour list, raising an error if neither contain the string. To explicitly select these lists, set the `colour_list' argument to either `molmol' or `x11'.

10.2.109.6 Examples

To map the order parameter values, $ S^2$ , onto the structure using the classic style, type:


relax> pymol.
[0]
[0]macro_exec(
[0]
[0]`S2')


relax> pymol.
[0]
[0]macro_exec(
[0]
[0]data_type=
[0]
[0]`S2')


relax> pymol.
[0]
[0]macro_exec(
[0]
[0]data_type=
[0]
[0]`S2', style=
[0]
[0]"classic")





10.2.110 pymol.tensor_pdb()

10.2.110.1 Synopsis

Function displaying the diffusion tensor PDB geometric object over the loaded PDB.

10.2.110.2 Defaults

pymol.
[0]tensor_pdb
(
[0]self, file=
[0]None)

10.2.110.3 Keyword Arguments

file: The name of the PDB file containing the tensor geometric object.

10.2.110.4 Description

In executing this user function, a PDB file must have previously been loaded into this data pipe a geometric object or polygon representing the Brownian rotational diffusion tensor will be overlain with the loaded PDB file and displayed within PyMOL. The PDB file containing the geometric object must be created using the complementary `pdb.create_diff_tensor_pdb()' user function.

The tensor PDB file is read in using the command:

load file

The centre of mass residue `COM' is displayed using the commands:

select resn COM
show dots, `sele'
color blue, `sele'

The axes of the diffusion tensor, the residue `AXS', is displayed using the commands:

select resn AXS
hide (`sele')
show sticks, `sele'
color cyan, `sele'
label `sele', name

The simulation axes, the residues `SIM', are displayed using the commands:

select resn SIM
colour cyan, `sele'





10.2.111 pymol.vector_dist()

10.2.111.1 Synopsis

Function displaying the PDB file representation of the XH vector distribution.

10.2.111.2 Defaults

pymol.
[0]vector_dist
(
[0]self, file=
[0]`XH_dist.
[0]pdb')

10.2.111.3 Keyword Arguments

file: The name of the PDB file containing the vector distribution.

10.2.111.4 Description

A PDB file of the macromolecule must have previously been loaded as the vector distribution will be overlain with the macromolecule within PyMOL. The PDB file containing the vector distribution must be created using the complementary `pdb.create_vector_dist()' user function.

The vector distribution PDB file is read in using the command:

load file





10.2.112 pymol.view()

10.2.112.1 Synopsis

Function for viewing the collection of molecules extracted from the PDB file.

10.2.112.2 Defaults

pymol.
[0]view
(
[0]self)

10.2.112.3 Example


relax> pymol.
[0]
[0]view(
[0]
[0])





10.2.113 pymol.write()

10.2.113.1 Synopsis

Function for creating PyMOL macros.

10.2.113.2 Defaults

pymol.
[0]write
(
[0]self, data_type=
[0]None, style=
[0]`classic', colour_start=
[0]None, colour_end=
[0]None, colour_list=
[0]None, file=
[0]None, dir=
[0]`pymol', force=
[0]False)

10.2.113.3 Keyword Arguments

data_type: The data type to map to the structure.

style: The style of the macro.

colour_start: The starting colour, either an array or string, of the linear colour gradient.

colour_end: The ending colour, either an array or string, of the linear colour gradient.

colour_list: The list of colours to match the start and end strings.

file: The name of the file.

dir: The directory name.

force: A flag which, if set to True, will cause the file to be overwritten.

10.2.113.4 Description

This function allows residues specific values to be mapped to a structure through the creation of a PyMOL macro which can be executed in PyMOL by clicking on `File, Macro, Execute User...'. Currently only the `classic' style, which is described below, is available.

10.2.113.5 Colour

The values are coloured based on a linear colour gradient which is specified through the `colour_start' and `colour_end' arguments. These arguments can either be a string to identify one of the RGB (red, green, blue) colour arrays listed in the tables below, or you can give the RGB vector itself. For example, colour_start=`white' and colour_start=[1.0, 1.0, 1.0] both select the same colour. Leaving both arguments at None will select the default colour gradient which for each type of analysis is described below.

When supplying the colours as strings, two lists of colours can be selected from which to match the strings. These are the default PyMOL colour list and the X11 colour list, both of which are described in the tables below. The default behaviour is to first search the PyMOL list and then the X11 colour list, raising an error if neither contain the string. To explicitly select these lists, set the `colour_list' argument to either `molmol' or `x11'.

10.2.113.6 Examples

To create a PyMOL macro mapping the order parameter values, $ S^2$ , onto the structure using the classic style, type:


relax> pymol.
[0]
[0]write(
[0]
[0]`S2')


relax> pymol.
[0]
[0]write(
[0]
[0]data_type=
[0]
[0]`S2')


relax> pymol.
[0]
[0]write(
[0]
[0]data_type=
[0]
[0]`S2', style=
[0]
[0]"classic", file=
[0]
[0]`s2.
[0]
[0]mac', dir=
[0]
[0]`pymol')


10.2.113.7 Molmol RGB colour arrays

The following table is a list of colours used in Molmol and their corresponding RGB colour values ranging from 0 to 1.

(see table 10.20)

Table: First table for the pymol.write() user function.
Name Red Green Blue
`black' 0.000 0.000 0.000
`navy' 0.000 0.000 0.502
`blue' 0.000 0.000 1.000
`dark green' 0.000 0.392 0.000
`green' 0.000 1.000 0.000
`cyan' 0.000 1.000 1.000
`turquoise' 0.251 0.878 0.816
`royal blue' 0.255 0.412 0.882
`aquamarine' 0.498 1.000 0.831
`sky green' 0.529 0.808 0.922
`dark violet' 0.580 0.000 0.827
`pale green' 0.596 0.984 0.596
`purple' 0.627 0.125 0.941
`brown' 0.647 0.165 0.165
`light blue' 0.678 0.847 0.902
`grey' 0.745 0.745 0.745
`light grey' 0.827 0.827 0.827
`violet' 0.933 0.510 0.933
`light coral' 0.941 0.502 0.502
`khaki' 0.941 0.902 0.549
`beige' 0.961 0.961 0.863
`red' 1.000 0.000 0.000
`magenta' 1.000 0.000 1.000
`deep pink' 1.000 0.078 0.576
`orange red' 1.000 0.271 0.000
`hot pink' 1.000 0.412 0.706
`coral' 1.000 0.498 0.314
`dark orange' 1.000 0.549 0.000
`orange' 1.000 0.647 0.000
`pink' 1.000 0.753 0.796
`gold' 1.000 0.843 0.000
`yellow' 1.000 1.000 0.000
`light yellow' 1.000 1.000 0.878
`ivory' 1.000 1.000 0.941
`white' 1.000 1.000 1.000

10.2.113.8 X11 RGB colour arrays

The following table is the list of X11 colour names and their corresponding RGB colour values ranging from 0 to 255.

(see table 10.21)

Table: Second table for the pymol.write() user function.

Name Red Green Blue

snow

255 250 250
ghost white 248 248 255
white smoke 245 245 245
gainsboro 220 220 220
floral white 255 250 240
old lace 253 245 230
linen 250 240 230
antique white 250 235 215
papaya whip 255 239 213
blanched almond 255 235 205
bisque 255 228 196
peach puff 255 218 185
navajo white 255 222 173
moccasin 255 228 181
cornsilk 255 248 220
ivory 255 255 240
lemon chiffon 255 250 205
seashell 255 245 238
honeydew 240 255 240
mint cream 245 255 250
azure 240 255 255
alice blue 240 248 255
lavender 230 230 250
lavender blush 255 240 245
misty rose 255 228 225
white 255 255 255
black 0 0 0
dark slate grey 47 79 79
dim grey 105 105 105
slate grey 112 128 144
light slate grey 119 136 153
grey 190 190 190
light grey 211 211 211
midnight blue 25 25 112
navy 0 0 128
cornflower blue 100 149 237
dark slate blue 72 61 139
slate blue 106 90 205
medium slate blue 123 104 238
light slate blue 132 112 255
medium blue 0 0 205
royal blue 65 105 225
blue 0 0 255
dodger blue 30 144 255
deep sky blue 0 191 255
sky blue 135 206 235
light sky blue 135 206 250
steel blue 70 130 180
light steel blue 176 196 222
light blue 173 216 230
powder blue 176 224 230
pale turquoise 175 238 238
dark turquoise 0 206 209
medium turquoise 72 209 204
turquoise 64 224 208
cyan 0 255 255
light cyan 224 255 255
cadet blue 95 158 160
medium aquamarine 102 205 170
aquamarine 127 255 212
dark green 0 100 0
dark olive green 85 107 47
dark sea green 143 188 143
sea green 46 139 87
medium sea green 60 179 113
light sea green 32 178 170
pale green 152 251 152
spring green 0 255 127
lawn green 124 252 0
green 0 255 0
chartreuse 127 255 0
medium spring green 0 250 154
green yellow 173 255 47
lime green 50 205 50
yellow green 154 205 50
forest green 34 139 34
olive drab 107 142 35
dark khaki 189 183 107
khaki 240 230 140
pale goldenrod 238 232 170
light goldenrod yellow 250 250 210
light yellow 255 255 224
yellow 255 255 0
gold 255 215 0
light goldenrod 238 221 130
goldenrod 218 165 32
dark goldenrod 184 134 11
rosy brown 188 143 143
indian red 205 92 92
saddle brown 139 69 19
sienna 160 82 45
peru 205 133 63
burlywood 222 184 135
beige 245 245 220
wheat 245 222 179
sandy brown 244 164 96
tan 210 180 140
chocolate 210 105 30
firebrick 178 34 34
brown 165 42 42
dark salmon 233 150 122
salmon 250 128 114
light salmon 255 160 122
orange 255 165 0
dark orange 255 140 0
coral 255 127 80
light coral 240 128 128
tomato 255 99 71
orange red 255 69 0
red 255 0 0
hot pink 255 105 180
deep pink 255 20 147
pink 255 192 203
light pink 255 182 193
pale violet red 219 112 147
maroon 176 48 96
medium violet red 199 21 133
violet red 208 32 144
magenta 255 0 255
violet 238 130 238
plum 221 160 221
orchid 218 112 214
medium orchid 186 85 211
dark orchid 153 50 204
dark violet 148 0 211
blue violet 138 43 226
purple 160 32 240
medium purple 147 112 219
thistle 216 191 216
snow 1 255 250 250
snow 2 238 233 233
snow 3 205 201 201
snow 4 139 137 137
seashell 1 255 245 238
seashell 2 238 229 222
seashell 3 205 197 191
seashell 4 139 134 130
antique white 1 255 239 219
antique white 2 238 223 204
antique white 3 205 192 176
antique white 4 139 131 120
bisque 1 255 228 196
bisque 2 238 213 183
bisque 3 205 183 158
bisque 4 139 125 107
peach puff 1 255 218 185
peach puff 2 238 203 173
peach puff 3 205 175 149
peach puff 4 139 119 101
navajo white 1 255 222 173
navajo white 2 238 207 161
navajo white 3 205 179 139
navajo white 4 139 121 94
lemon chiffon 1 255 250 205
lemon chiffon 2 238 233 191
lemon chiffon 3 205 201 165
lemon chiffon 4 139 137 112
cornsilk 1 255 248 220
cornsilk 2 238 232 205
cornsilk 3 205 200 177
cornsilk 4 139 136 120
ivory 1 255 255 240
ivory 2 238 238 224
ivory 3 205 205 193
ivory 4 139 139 131
honeydew 1 240 255 240
honeydew 2 224 238 224
honeydew 3 193 205 193
honeydew 4 131 139 131
lavender blush 1 255 240 245
lavender blush 2 238 224 229
lavender blush 3 205 193 197
lavender blush 4 139 131 134
misty rose 1 255 228 225
misty rose 2 238 213 210
misty rose 3 205 183 181
misty rose 4 139 125 123
azure 1 240 255 255
azure 2 224 238 238
azure 3 193 205 205
azure 4 131 139 139
slate blue 1 131 111 255
slate blue 2 122 103 238
slate blue 3 105 89 205
slate blue 4 71 60 139
royal blue 1 72 118 255
royal blue 2 67 110 238
royal blue 3 58 95 205
royal blue 4 39 64 139
blue 1 0 0 255
blue 2 0 0 238
blue 3 0 0 205
blue 4 0 0 139
dodger blue 1 30 144 255
dodger blue 2 28 134 238
dodger blue 3 24 116 205
dodger blue 4 16 78 139
steel blue 1 99 184 255
steel blue 2 92 172 238
steel blue 3 79 148 205
steel blue 4 54 100 139
deep sky blue 1 0 191 255
deep sky blue 2 0 178 238
deep sky blue 3 0 154 205
deep sky blue 4 0 104 139
sky blue 1 135 206 255
sky blue 2 126 192 238
sky blue 3 108 166 205
sky blue 4 74 112 139
light sky blue 1 176 226 255
light sky blue 2 164 211 238
light sky blue 3 141 182 205
light sky blue 4 96 123 139
slate grey 1 198 226 255
slate grey 2 185 211 238
slate grey 3 159 182 205
slate grey 4 108 123 139
light steel blue 1 202 225 255
light steel blue 2 188 210 238
light steel blue 3 162 181 205
light steel blue 4 110 123 139
light blue 1 191 239 255
light blue 2 178 223 238
light blue 3 154 192 205
light blue 4 104 131 139
light cyan 1 224 255 255
light cyan 2 209 238 238
light cyan 3 180 205 205
light cyan 4 122 139 139
pale turquoise 1 187 255 255
pale turquoise 2 174 238 238
pale turquoise 3 150 205 205
pale turquoise 4 102 139 139
cadet blue 1 152 245 255
cadet blue 2 142 229 238
cadet blue 3 122 197 205
cadet blue 4 83 134 139
turquoise 1 0 245 255
turquoise 2 0 229 238
turquoise 3 0 197 205
turquoise 4 0 134 139
cyan 1 0 255 255
cyan 2 0 238 238
cyan 3 0 205 205
cyan 4 0 139 139
dark slate grey 1 151 255 255
dark slate grey 2 141 238 238
dark slate grey 3 121 205 205
dark slate grey 4 82 139 139
aquamarine 1 127 255 212
aquamarine 2 118 238 198
aquamarine 3 102 205 170
aquamarine 4 69 139 116
dark sea green 1 193 255 193
dark sea green 2 180 238 180
dark sea green 3 155 205 155
dark sea green 4 105 139 105
sea green 1 84 255 159
sea green 2 78 238 148
sea green 3 67 205 128
sea green 4 46 139 87
pale green 1 154 255 154
pale green 2 144 238 144
pale green 3 124 205 124
pale green 4 84 139 84
spring green 1 0 255 127
spring green 2 0 238 118
spring green 3 0 205 102
spring green 4 0 139 69
green 1 0 255 0
green 2 0 238 0
green 3 0 205 0
green 4 0 139 0
chartreuse 1 127 255 0
chartreuse 2 118 238 0
chartreuse 3 102 205 0
chartreuse 4 69 139 0
olive drab 1 192 255 62
olive drab 2 179 238 58
olive drab 3 154 205 50
olive drab 4 105 139 34
dark olive green 1 202 255 112
dark olive green 2 188 238 104
dark olive green 3 162 205 90
dark olive green 4 110 139 61
khaki 1 255 246 143
khaki 2 238 230 133
khaki 3 205 198 115
khaki 4 139 134 78
light goldenrod 1 255 236 139
light goldenrod 2 238 220 130
light goldenrod 3 205 190 112
light goldenrod 4 139 129 76
light yellow 1 255 255 224
light yellow 2 238 238 209
light yellow 3 205 205 180
light yellow 4 139 139 122
yellow 1 255 255 0
yellow 2 238 238 0
yellow 3 205 205 0
yellow 4 139 139 0
gold 1 255 215 0
gold 2 238 201 0
gold 3 205 173 0
gold 4 139 117 0
goldenrod 1 255 193 37
goldenrod 2 238 180 34
goldenrod 3 205 155 29
goldenrod 4 139 105 20
dark goldenrod 1 255 185 15
dark goldenrod 2 238 173 14
dark goldenrod 3 205 149 12
dark goldenrod 4 139 101 8
rosy brown 1 255 193 193
rosy brown 2 238 180 180
rosy brown 3 205 155 155
rosy brown 4 139 105 105
indian red 1 255 106 106
indian red 2 238 99 99
indian red 3 205 85 85
indian red 4 139 58 58
sienna 1 255 130 71
sienna 2 238 121 66
sienna 3 205 104 57
sienna 4 139 71 38
burlywood 1 255 211 155
burlywood 2 238 197 145
burlywood 3 205 170 125
burlywood 4 139 115 85
wheat 1 255 231 186
wheat 2 238 216 174
wheat 3 205 186 150
wheat 4 139 126 102
tan 1 255 165 79
tan 2 238 154 73
tan 3 205 133 63
tan 4 139 90 43
chocolate 1 255 127 36
chocolate 2 238 118 33
chocolate 3 205 102 29
chocolate 4 139 69 19
firebrick 1 255 48 48
firebrick 2 238 44 44
firebrick 3 205 38 38
firebrick 4 139 26 26
brown 1 255 64 64
brown 2 238 59 59
brown 3 205 51 51
brown 4 139 35 35
salmon 1 255 140 105
salmon 2 238 130 98
salmon 3 205 112 84
salmon 4 139 76 57
light salmon 1 255 160 122
light salmon 2 238 149 114
light salmon 3 205 129 98
light salmon 4 139 87 66
orange 1 255 165 0
orange 2 238 154 0
orange 3 205 133 0
orange 4 139 90 0
dark orange 1 255 127 0
dark orange 2 238 118 0
dark orange 3 205 102 0
dark orange 4 139 69 0
coral 1 255 114 86
coral 2 238 106 80
coral 3 205 91 69
coral 4 139 62 47
tomato 1 255 99 71
tomato 2 238 92 66
tomato 3 205 79 57
tomato 4 139 54 38
orange red 1 255 69 0
orange red 2 238 64 0
orange red 3 205 55 0
orange red 4 139 37 0
red 1 255 0 0
red 2 238 0 0
red 3 205 0 0
red 4 139 0 0
deep pink 1 255 20 147
deep pink 2 238 18 137
deep pink 3 205 16 118
deep pink 4 139 10 80
hot pink 1 255 110 180
hot pink 2 238 106 167
hot pink 3 205 96 144
hot pink 4 139 58 98
pink 1 255 181 197
pink 2 238 169 184
pink 3 205 145 158
pink 4 139 99 108
light pink 1 255 174 185
light pink 2 238 162 173
light pink 3 205 140 149
light pink 4 139 95 101
pale violet red 1 255 130 171
pale violet red 2 238 121 159
pale violet red 3 205 104 137
pale violet red 4 139 71 93
maroon 1 255 52 179
maroon 2 238 48 167
maroon 3 205 41 144
maroon 4 139 28 98
violet red 1 255 62 150
violet red 2 238 58 140
violet red 3 205 50 120
violet red 4 139 34 82
magenta 1 255 0 255
magenta 2 238 0 238
magenta 3 205 0 205
magenta 4 139 0 139
orchid 1 255 131 250
orchid 2 238 122 233
orchid 3 205 105 201
orchid 4 139 71 137
plum 1 255 187 255
plum 2 238 174 238
plum 3 205 150 205
plum 4 139 102 139
medium orchid 1 224 102 255
medium orchid 2 209 95 238
medium orchid 3 180 82 205
medium orchid 4 122 55 139
dark orchid 1 191 62 255
dark orchid 2 178 58 238
dark orchid 3 154 50 205
dark orchid 4 104 34 139
purple 1 155 48 255
purple 2 145 44 238
purple 3 125 38 205
purple 4 85 26 139
medium purple 1 171 130 255
medium purple 2 159 121 238
medium purple 3 137 104 205
medium purple 4 93 71 139
thistle 1 255 225 255
thistle 2 238 210 238
thistle 3 205 181 205
thistle 4 139 123 139
grey 0 0 0 0
grey 1 3 3 3
grey 2 5 5 5
grey 3 8 8 8
grey 4 10 10 10
grey 5 13 13 13
grey 6 15 15 15
grey 7 18 18 18
grey 8 20 20 20
grey 9 23 23 23
grey 10 26 26 26
grey 11 28 28 28
grey 12 31 31 31
grey 13 33 33 33
grey 14 36 36 36
grey 15 38 38 38
grey 16 41 41 41
grey 17 43 43 43
grey 18 46 46 46
grey 19 48 48 48
grey 20 51 51 51
grey 21 54 54 54
grey 22 56 56 56
grey 23 59 59 59
grey 24 61 61 61
grey 25 64 64 64
grey 26 66 66 66
grey 27 69 69 69
grey 28 71 71 71
grey 29 74 74 74
grey 30 77 77 77
grey 31 79 79 79
grey 32 82 82 82
grey 33 84 84 84
grey 34 87 87 87
grey 35 89 89 89
grey 36 92 92 92
grey 37 94 94 94
grey 38 97 97 97
grey 39 99 99 99
grey 40 102 102 102
grey 41 105 105 105
grey 42 107 107 107
grey 43 110 110 110
grey 44 112 112 112
grey 45 115 115 115
grey 46 117 117 117
grey 47 120 120 120
grey 48 122 122 122
grey 49 125 125 125
grey 50 127 127 127
grey 51 130 130 130
grey 52 133 133 133
grey 53 135 135 135
grey 54 138 138 138
grey 55 140 140 140
grey 56 143 143 143
grey 57 145 145 145
grey 58 148 148 148
grey 59 150 150 150
grey 60 153 153 153
grey 61 156 156 156
grey 62 158 158 158
grey 63 161 161 161
grey 64 163 163 163
grey 65 166 166 166
grey 66 168 168 168
grey 67 171 171 171
grey 68 173 173 173
grey 69 176 176 176
grey 70 179 179 179
grey 71 181 181 181
grey 72 184 184 184
grey 73 186 186 186
grey 74 189 189 189
grey 75 191 191 191
grey 76 194 194 194
grey 77 196 196 196
grey 78 199 199 199
grey 79 201 201 201
grey 80 204 204 204
grey 81 207 207 207
grey 82 209 209 209
grey 83 212 212 212
grey 84 214 214 214
grey 85 217 217 217
grey 86 219 219 219
grey 87 222 222 222
grey 88 224 224 224
grey 89 227 227 227
grey 90 229 229 229
grey 91 232 232 232
grey 92 235 235 235
grey 93 237 237 237
grey 94 240 240 240
grey 95 242 242 242
grey 96 245 245 245
grey 97 247 247 247
grey 98 250 250 250
grey 99 252 252 252
grey 100 255 255 255
dark grey 169 169 169
dark blue 0 0 139
dark cyan 0 139 139
dark magenta 139 0 139
dark red 139 0 0
light green 144 238 144





10.2.114 rdc.back_calc()

10.2.114.1 Synopsis

Back calculate RDCs.

10.2.114.2 Defaults

rdc.
[0]
[0]back_calc
(
[0]self, align_id=
[0]None)

10.2.114.3 Keyword Arguments

align_id: The alignment ID string.





10.2.115 rdc.calc_q_factors()

10.2.115.1 Synopsis

Calculate the RDC Q-factor for the selected spins.

10.2.115.2 Defaults

rdc.
[0]
[0]calc_q_factors
(
[0]self, spin_id=
[0]None)

10.2.115.3 Keyword Arguments

spin_id: The spin ID string for restricting to subset of all selected spins.

10.2.115.4 Description

For this function to work, the back-calculated RDC data must first be generated by the analysis specific code. Otherwise a warning will be given.

10.2.115.5 Examples

To calculate the RDC Q-factor for only the spins `@H26', `@H27', and `@H28', type one of:


relax> rdc.
[0]
[0]
[0]calc_q_factors(
[0]
[0]`@H26 & @H27 & @H28')


relax> rdc.
[0]
[0]
[0]calc_q_factors(
[0]
[0]spin_id=
[0]
[0]`@H26 & @H27 & @H28')





10.2.116 rdc.copy()

10.2.116.1 Synopsis

Copy RDC data from pipe_from to pipe_to.

10.2.116.2 Defaults

rdc.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, pipe_to=
[0]None, align_id=
[0]None)

10.2.116.3 Keyword Arguments

pipe_from: The name of the pipe to copy the RDC data from.

pipe_to: The name of the pipe to copy the RDC data to.

align_id: The alignment ID string.

10.2.116.4 Description

This function will copy RDC data from `pipe_from' to `pipe_to'. If align_id is not given then all RDC data will be copied, otherwise only a specific data set will be.

10.2.116.5 Examples

To copy all RDC data from pipe `m1' to pipe `m9', type one of:


relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9')


relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9')


relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9', None)


relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9', align_id=
[0]
[0]None)

To copy only the `Th' RDC data from `m3' to `m6', type one of:


relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]`m3', `m6', `Th')


relax> rdc.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m3', pipe_to=
[0]
[0]`m6', align_id=
[0]
[0]`Th')





10.2.117 rdc.corr_plot()

10.2.117.1 Synopsis

Generate a correlation plot of the measured vs. the back-calculated RDCs.

10.2.117.2 Defaults

rdc.
[0]
[0]corr_plot
(
[0]self, format=
[0]`grace', file=
[0]`rdc_corr_plot.
[0]
[0]agr', dir=
[0]None, force=
[0]False)

10.2.117.3 Keyword Arguments

format: The format of the plot data.

file: The name of the file.

dir: The directory name.

force: A flag which if True will cause the file to be overwritten.

10.2.117.4 Description

Two formats are currently supported. If format is set to `grace', then a Grace plot file will be created. If the format arg is set to None, then a plain text list of the measured and back-calculated data will be created.

10.2.117.5 Examples

To create a Grace plot of the data, type:


relax> rdc.
[0]
[0]
[0]corr_plot(
[0]
[0])

To create a plain text list of the measured and back-calculated data, type one of:


relax> rdc.
[0]
[0]
[0]corr_plot(
[0]
[0]None)


relax> rdc.
[0]
[0]
[0]corr_plot(
[0]
[0]format=
[0]
[0]None)





10.2.118 rdc.delete()

10.2.118.1 Synopsis

Delete the RDC data corresponding to the alignment ID.

10.2.118.2 Defaults

rdc.
[0]
[0]delete
(
[0]self, align_id=
[0]None)

10.2.118.3 Keyword Arguments

align_id: The alignment ID string.

10.2.118.4 Examples

To delete the RDC data corresponding to align_id=`PH_gel', type:


relax> rdc.
[0]
[0]
[0]delete(
[0]
[0]`PH_gel')





10.2.119 rdc.display()

10.2.119.1 Synopsis

Display the RDC data corresponding to the alignment ID.

10.2.119.2 Defaults

rdc.
[0]
[0]display
(
[0]self, align_id=
[0]None)

10.2.119.3 Keyword Arguments

align_id: The alignment ID string.

10.2.119.4 Examples

To display the `phage' RDC data, type:


relax> rdc.
[0]
[0]
[0]display(
[0]
[0]`phage')





10.2.120 rdc.read()

10.2.120.1 Synopsis

Read the RDC data from file.

10.2.120.2 Defaults

rdc.
[0]read
(
[0]self, align_id=
[0]None, file=
[0]None, dir=
[0]None, spin_id_col=
[0]None, mol_name_col=
[0]None, res_num_col=
[0]None, res_name_col=
[0]None, spin_num_col=
[0]None, spin_name_col=
[0]None, data_col=
[0]None, error_col=
[0]None, sep=
[0]None, spin_id=
[0]None, neg_g_corr=
[0]False)

10.2.120.3 Keyword Arguments

align_id: The alignment ID string.

file: The name of the file containing the RDC data.

dir: The directory where the file is located.

spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).

mol_name_col: The molecule name column (alternative to the spin_id_col).

res_num_col: The residue number column (alternative to the spin_id_col).

res_name_col: The residue name column (alternative to the spin_id_col).

spin_num_col: The spin number column (alternative to the spin_id_col).

spin_name_col: The spin name column (alternative to the spin_id_col).

data_col: The RDC data column.

error_col: The experimental error column.

sep: The column separator (the default is white space).

spin_id: The spin ID string to restrict the loading of data to certain spin subsets.

neg_g_corr: A flag which is used to correct for the negative gyromagnetic ratio of 15N.

10.2.120.4 Description

The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.

If neg_g_corr is set to True, a sign inversion will be applied to all RDC values to be loaded.

10.2.120.5 Examples

The following commands will read the RDC data out of the file `Tb.txt' where the columns are separated by the symbol `,', and store the RDCs under the ID `Tb'.


relax> rdc.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', sep=
[0]
[0]`,')

If the individual spin RDC errors are located in the file `rdc_err.txt' in column number 5, then to read these values into relax, type one of:


relax> rdc.
[0]
[0]read(
[0]
[0]`phage', `rdc_err.
[0]
[0]txt', error_col=
[0]
[0]5)


relax> rdc.
[0]
[0]read(
[0]
[0]align_id=
[0]
[0]`phage', file=
[0]
[0]`rdc_err.
[0]
[0]txt', error_col=
[0]
[0]5)

If the RDCs correspond to the `N' spin and other spin types such as 1H, 13C, etc. are loaded into relax, then type:


relax> rdc.
[0]
[0]read(
[0]
[0]`Tb', `Tb.
[0]
[0]txt', spin_id=
[0]
[0]`@N')





10.2.121 rdc.weight()

10.2.121.1 Synopsis

Set optimisation weights on the RDC data.

10.2.121.2 Defaults

rdc.
[0]weight
(
[0]self, align_id=
[0]None, spin_id=
[0]None, weight=
[0]1.0)

10.2.121.3 Keyword Arguments

align_id: The alignment ID string.

spin_id: The spin ID string.

weight: The weighting value.

10.2.121.4 Description

This function can be used to force the RDC to contribute more or less to the chi-squared optimisation statistic. The higher the value, the more importance the RDC will have.





10.2.122 rdc.write()

10.2.122.1 Synopsis

Write the RDC data to file.

10.2.122.2 Defaults

rdc.
[0]write
(
[0]self, align_id=
[0]None, file=
[0]None, dir=
[0]None, force=
[0]False)

10.2.122.3 Keyword Arguments

align_id: The alignment ID string.

file: The name of the file.

dir: The directory name.

force: A flag which if True will cause the file to be overwritten.

10.2.122.4 Description

If no directory name is given, the file will be placed in the current working directory. The `align_id' argument are required for selecting which RDC data set will be written to file.





10.2.123 relax_data.back_calc()

10.2.123.1 Synopsis

Function for back calculating relaxation data.

10.2.123.2 Defaults

relax_data.
[0]
[0]back_calc
(
[0]self, ri_id=
[0]None, ri_type=
[0]None, frq=
[0]None)

10.2.123.3 Keyword Arguments

ri_id: The relaxation data ID string.

ri_type: The relaxation data type, ie `R1', `R2', or `NOE'.

frq: The spectrometer frequency in Hz.





10.2.124 relax_data.copy()

10.2.124.1 Synopsis

Copy relaxation data from one pipe to another.

10.2.124.2 Defaults

relax_data.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, pipe_to=
[0]None, ri_id=
[0]None)

10.2.124.3 Keyword Arguments

pipe_from: The name of the pipe to copy the relaxation data from.

pipe_to: The name of the pipe to copy the relaxation data to.

ri_id: The relaxation data ID string.

10.2.124.4 Description

This function will copy relaxation data from `pipe_from' to `pipe_to'. If ri_id is not given then all relaxation data will be copied, otherwise only a specific data set will be copied.

10.2.124.5 Examples

To copy all relaxation data from pipe `m1' to pipe `m9', type one of:


relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9')


relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9')


relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m9', None)


relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m9', ri_id=
[0]
[0]None)

To copy only the NOE relaxation data with the ID string of `NOE_800' from `m3' to `m6', type one of:


relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]`m3', `m6', `NOE_800')


relax> relax_data.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m3', pipe_to=
[0]
[0]`m6', ri_id=
[0]
[0]`NOE_800')





10.2.125 relax_data.delete()

10.2.125.1 Synopsis

Delete the data corresponding to the relaxation data ID string.

10.2.125.2 Defaults

relax_data.
[0]
[0]delete
(
[0]self, ri_id=
[0]None)

10.2.125.3 Keyword Arguments

ri_id: The relaxation data ID string.

10.2.125.4 Examples

To delete the relaxation data corresponding to the ID `NOE_600', type:


relax> relax_data.
[0]
[0]
[0]delete(
[0]
[0]`NOE_600')





10.2.126 relax_data.display()

10.2.126.1 Synopsis

Display the data corresponding to the relaxation data ID string.

10.2.126.2 Defaults

relax_data.
[0]
[0]display
(
[0]self, ri_id=
[0]None)

10.2.126.3 Keyword Arguments

ri_id: The relaxation data ID string.

10.2.126.4 Examples

To display the NOE relaxation data at 600 MHz with the ID string `NOE_600', type:


relax> relax_data.
[0]
[0]
[0]display(
[0]
[0]`NOE_600')





10.2.127 relax_data.peak_intensity_type()

10.2.127.1 Synopsis

Specify the type of peak intensity measurement used - $ i$ .e. height or volume.

10.2.127.2 Defaults

relax_data.
[0]peak_intensity_type
(
[0]self, ri_id=
[0]None, type=
[0]None)

10.2.127.3 Keyword Arguments

ri_id: The relaxation data ID string.

type: The peak intensity type.

10.2.127.4 Description

This user function is essential for BMRB data deposition. This is used to specify whether peak heights or peak volumes were measured. The two currently allowed values for the type argument are `height' and `volume'.





10.2.128 relax_data.read()

10.2.128.1 Synopsis

Read R$ _1$ , R$ _2$ , or NOE relaxation data from a file.

10.2.128.2 Defaults

relax_data.
[0]read
(
[0]self, ri_id=
[0]None, ri_type=
[0]None, frq=
[0]None, file=
[0]None, dir=
[0]None, spin_id_col=
[0]None, mol_name_col=
[0]None, res_num_col=
[0]None, res_name_col=
[0]None, spin_num_col=
[0]None, spin_name_col=
[0]None, data_col=
[0]None, error_col=
[0]None, sep=
[0]None, spin_id=
[0]None)

10.2.128.3 Keyword Arguments

ri_id: The relaxation data ID string.

ri_type: The relaxation data type, ie `R1', `R2', or `NOE'.

frq: The spectrometer frequency in Hz.

file: The name of the file containing the relaxation data.

dir: The directory where the file is located.

spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).

mol_name_col: The molecule name column (alternative to the spin_id_col).

res_num_col: The residue number column (alternative to the spin_id_col).

res_name_col: The residue name column (alternative to the spin_id_col).

spin_num_col: The spin number column (alternative to the spin_id_col).

spin_name_col: The spin name column (alternative to the spin_id_col).

data_col: The relaxation data column.

error_col: The experimental error column.

sep: The column separator (the default is white space).

spin_id: The spin ID string to restrict the loading of data to certain spin subsets.

10.2.128.4 Description

The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.

The frequency label argument can be anything as long as data collected at the same field strength have the same label.

10.2.128.5 Examples

The following commands will read the protein NOE relaxation data collected at 600 MHz out of a file called `noe.600.out' where the residue numbers, residue names, data, errors are in the first, second, third, and forth columns respectively.


relax> relax_data.
[0]
[0]read(
[0]
[0]`NOE_600', `NOE', 599.7 * 1e6, `noe.600.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, data_col=
[0]
[0]3, error_col=
[0]
[0]4)


relax> relax_data.
[0]
[0]read(
[0]
[0]ri_id=
[0]
[0]`NOE_600', ri_type=
[0]
[0]`NOE', frq=
[0]
[0]600.0 * 1e6, file=
[0]
[0]`noe.600.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, data_col=
[0]
[0]3, error_col=
[0]
[0]4)

The following commands will read the R$ _2$ data out of the file `r2.out' where the residue numbers, residue names, data, errors are in the second, third, fifth, and sixth columns respectively. The columns are separated by commas.


relax> relax_data.
[0]
[0]read(
[0]
[0]`R2_800', `R2', 8.0 * 1e8, `r2.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]3, data_col=
[0]
[0]5, error_col=
[0]
[0]6, sep=
[0]
[0]`,')


relax> relax_data.
[0]
[0]read(
[0]
[0]ri_id=
[0]
[0]`R2_800', ri_type=
[0]
[0]`R2', frq=
[0]
[0]8.0*1e8, file=
[0]
[0]`r2.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]3, data_col=
[0]
[0]5, error_col=
[0]
[0]6, sep=
[0]
[0]`,')

The following commands will read the R$ _1$ data out of the file `r1.out' where the columns are separated by the symbol `%'


relax> relax_data.
[0]
[0]read(
[0]
[0]`R1_300', `R1', 300.1 * 1e6, `r1.
[0]
[0]out', sep=
[0]
[0]`%')





10.2.129 relax_data.temp_calibration()

10.2.129.1 Synopsis

Specify the temperature calibration method used.

10.2.129.2 Defaults

relax_data.
[0]temp_calibration
(
[0]self, ri_id=
[0]None, method=
[0]None)

10.2.129.3 Keyword Arguments

ri_id: The relaxation data ID string.

method: The calibration method.

10.2.129.4 Description

This user function is essential for BMRB data deposition. The currently allowed methods are

`methanol',
`monoethylene glycol',
`no calibration applied'.

Other strings will be accepted if supplied.





10.2.130 relax_data.temp_control()

10.2.130.1 Synopsis

Specify the temperature control method used.

10.2.130.2 Defaults

relax_data.
[0]temp_control
(
[0]self, ri_id=
[0]None, method=
[0]None)

10.2.130.3 Keyword Arguments

ri_id: The relaxation data ID string.

method: The control method.

10.2.130.4 Description

This user function is essential for BMRB data deposition. The currently allowed methods are

`single scan interleaving',
`temperature compensation block',
`single scan interleaving and temperature compensation block',
`single fid interleaving',
`single experiment interleaving',
`no temperature control applied'.





10.2.131 relax_data.write()

10.2.131.1 Synopsis

Write relaxation data to a file.

10.2.131.2 Defaults

relax_data.
[0]write
(
[0]self, ri_id=
[0]None, file=
[0]None, dir=
[0]None, bc=
[0]False, force=
[0]False)

10.2.131.3 Keyword Arguments

ri_id: The relaxation data ID string.

file: The name of the file.

dir: The directory name.

bc: A flag which if True will cause the back calculated relaxation data to be written to file rather than the actual data.

force: A flag which if True will cause the file to be overwritten.

10.2.131.4 Description

If no directory name is given, the file will be placed in the current working directory. The `ri_id' argument is required for selecting which relaxation data to write to file.





10.2.132 relax_fit.relax_time()

10.2.132.1 Synopsis

Function for setting the relaxation time period associated with each spectrum.

10.2.132.2 Defaults

relax_fit.
[0]relax_time
(
[0]self, time=
[0]0.0, spectrum_id=
[0]None)

10.2.132.3 Keyword Arguments

time: The time, in seconds, of the relaxation period.

spectrum_id: The spectrum identification string.

10.2.132.4 Description

Peak intensities should be loaded before calling this user function via the `spectrum.read_intensities()' user function. The intensity values will then be associated with a spectrum identifier. To associate each spectrum identifier with a time point in the relaxation curve prior to optimisation, this user function should be called.





10.2.133 relax_fit.select_model()

10.2.133.1 Synopsis

Function for the selection of the relaxation curve type.

10.2.133.2 Defaults

relax_fit.
[0]select_model
(
[0]self, model=
[0]`exp')

10.2.133.3 Keyword Arguments

model: The type of relaxation curve to fit.

10.2.133.4 The preset models

The supported relaxation experiments include the default two parameter exponential fit, selected by setting the `fit_type' argument to `exp', and the three parameter inversion recovery experiment in which the peak intensity limit is a non-zero value, selected by setting the argument to `inv'.

The parameters of these two models are

`exp' -
[Rx, I0],
`inv' -
[Rx, I0, Iinf].





10.2.134 reset()

10.2.134.1 Synopsis

Reset relax.

10.2.134.2 Defaults

reset(
[0]self)

All of the data of the relax data storage object will be erased and hence relax will return to its initial state.





10.2.135 residue.copy()

10.2.135.1 Synopsis

Function for copying all data associated with a residue.

10.2.135.2 Defaults

residue.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, res_from=
[0]None, pipe_to=
[0]None, res_to=
[0]None)

10.2.135.3 Keyword Arguments

pipe_from: The data pipe containing the residue from which the data will be copied. This defaults to the current data pipe.

res_from: The residue identifier string of the residue to copy the data from.

pipe_to: The data pipe to copy the data to. This defaults to the current data pipe.

res_to: The residue identifier string of the residue to copy the data to.

10.2.135.4 Description

This function will copy all the data associated with the identified residue to the new, non-existent residue. The new residue must not already exist.

10.2.135.5 Examples

To copy the residue data from residue 1 to the new residue 2, type:


relax> residue.
[0]
[0]
[0]copy(
[0]
[0]res_from=
[0]
[0]`:1', res_to=
[0]
[0]`:2')

To copy residue 1 of the molecule `Old mol' to residue 5 of the molecule `New mol', type:


relax> residue.
[0]
[0]
[0]copy(
[0]
[0]res_from=
[0]
[0]`#Old mol:1', res_to=
[0]
[0]`#New mol:5')

To copy the residue data of residue 1 from the data pipe `m1' to `m2', assuming the current data pipe is `m1', type:


relax> residue.
[0]
[0]
[0]copy(
[0]
[0]res_from=
[0]
[0]`:1', pipe_to=
[0]
[0]`m2')


relax> residue.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', res_from=
[0]
[0]`:1', pipe_to=
[0]
[0]`m2', res_to=
[0]
[0]`:1')

10.2.135.6 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.136 residue.create()

10.2.136.1 Synopsis

Function for creating a new residue.

10.2.136.2 Defaults

residue.
[0]
[0]create
(
[0]self, res_num=
[0]None, res_name=
[0]None, mol_name=
[0]None)

10.2.136.3 Keyword Arguments

res_num: The residue number.

res_name: The name of the residue.

mol_name: The name of the molecule to add the residue to.

10.2.136.4 Description

Using this function a new sequence can be generated without using the sequence user functions. However if the sequence already exists, the new residue will be added to the end of the residue list (the residue numbers of this list need not be sequential). The same residue number cannot be used more than once. A corresponding single spin system will be created for this residue. The spin system number and name or additional spin systems can be added later if desired.

10.2.136.5 Examples

The following sequence of commands will generate the sequence 1 ALA, 2 GLY, 3 LYS:


relax> residue.
[0]
[0]
[0]create(
[0]
[0]1, `ALA')


relax> residue.
[0]
[0]
[0]create(
[0]
[0]2, `GLY')


relax> residue.
[0]
[0]
[0]create(
[0]
[0]3, `LYS')





10.2.137 residue.delete()

10.2.137.1 Synopsis

Function for deleting residues.

10.2.137.2 Defaults

residue.
[0]
[0]delete
(
[0]self, res_id=
[0]None)

10.2.137.3 Keyword Arguments

res_id: The residue identifier string.

10.2.137.4 Description

This function can be used to delete a single or sets of residues. See the identification string documentation below for more information. If spin system/atom ids are included a RelaxError will be raised.

10.2.137.5 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.138 residue.display()

10.2.138.1 Synopsis

Function for displaying information about the residue(s).

10.2.138.2 Defaults

residue.
[0]
[0]display
(
[0]self, res_id=
[0]None)

10.2.138.3 Keyword Arguments

res_id: The residue identification string.

10.2.138.4 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.139 residue.name()

10.2.139.1 Synopsis

Function for naming residues.

10.2.139.2 Defaults

residue.
[0]name
(
[0]self, res_id=
[0]None, name=
[0]None, force=
[0]False)

10.2.139.3 Keyword Arguments

res_id: The residue identification string corresponding to one or more residues.

name: The new name.

force: A flag which if True will cause the residue to be renamed.

10.2.139.4 Description

This function simply allows residues to be named (or renamed).

10.2.139.5 Examples

The following sequence of commands will rename the sequence {1 ALA, 2 GLY, 3 LYS} to {1 XXX, 2 XXX, 3 XXX}:


relax> residue.
[0]
[0]name(
[0]
[0]`:1', `XXX', force=
[0]
[0]True)


relax> residue.
[0]
[0]name(
[0]
[0]`:2', `XXX', force=
[0]
[0]True)


relax> residue.
[0]
[0]name(
[0]
[0]`:3', `XXX', force=
[0]
[0]True)

Alternatively:


relax> residue.
[0]
[0]name(
[0]
[0]`:1,2,3', `XXX', force=
[0]
[0]True)

10.2.139.6 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.140 residue.number()

10.2.140.1 Synopsis

Function for numbering residues.

10.2.140.2 Defaults

residue.
[0]number
(
[0]self, res_id=
[0]None, number=
[0]None, force=
[0]False)

10.2.140.3 Keyword Arguments

res_id: The residue identification string corresponding to a single residue.

number: The new residue number.

force: A flag which if True will cause the residue to be renumbered.

10.2.140.4 Description

This function simply allows residues to be numbered. The new number cannot correspond to an existing residue.

10.2.140.5 Examples

The following sequence of commands will renumber the sequence {1 ALA, 2 GLY, 3 LYS} to {101 ALA, 102 GLY, 103 LYS}:


relax> residue.
[0]
[0]number(
[0]
[0]`:1', 101, force=
[0]
[0]True)


relax> residue.
[0]
[0]number(
[0]
[0]`:2', 102, force=
[0]
[0]True)


relax> residue.
[0]
[0]number(
[0]
[0]`:3', 103, force=
[0]
[0]True)

10.2.140.6 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.141 results.display()

10.2.141.1 Synopsis

Function for displaying the results.

10.2.141.2 Defaults

results.
[0]
[0]display
(
[0]self)

10.2.141.3 Description

This will print to screen (STDOUT) the results contained within the current data pipe.





10.2.142 results.read()

10.2.142.1 Synopsis

Function for reading results from a file.

10.2.142.2 Defaults

results.
[0]read
(
[0]self, file=
[0]`results', dir=
[0]None)

10.2.142.3 Keyword Arguments

file: The name of the file to read results from.

dir: The directory where the file is located.

10.2.142.4 Description

To search for the results file in the current working directory, set dir to None.

This function is able to handle uncompressed, bzip2 compressed files, or gzip compressed files automatically. The full file name including extension can be supplied, however, if the file cannot be found, this function will search for the file name with `.bz2' appended followed by the file name with `.gz' appended.





10.2.143 results.write()

10.2.143.1 Synopsis

Function for writing results to a file.

10.2.143.2 Defaults

results.
[0]write
(
[0]self, file=
[0]`results', dir=
[0]`pipe_name', compress_type=
[0]1, force=
[0]False)

10.2.143.3 Keyword Arguments

file: The name of the file to output results to. The default is `results'. Optionally this can be a file object, or any object with a write() method.

dir: The directory name.

compress_type: The type of compression to use when creating the file.

force: A flag which if True will cause the results file to be overwritten.

10.2.143.4 Description

To place the results file in the current working directory, set dir to None. If dir is set to the special name `pipe_name', then the results file will be placed into a directory with the same name as the current data pipe.

The default behaviour of this function is to compress the file using bzip2 compression. If the extension `.bz2' is not included in the file name, it will be added. The compression can, however, be changed to either no compression or gzip compression. This is controlled by the compress_type argument which can be set to

0 -
No compression (no file extension),
1 -
bzip2 compression (`.bz2' file extension),
2 -
gzip compression (`.gz' file extension).

The complementary read function will automatically handle the compressed files.





10.2.144 select.all()

10.2.144.1 Synopsis

Function for selecting all spins.

10.2.144.2 Defaults

select.
[0]
[0]all
(
[0]self)

10.2.144.3 Examples

To select all spins, simply type:


relax> select.
[0]
[0]
[0]all(
[0]
[0])





10.2.145 select.read()

10.2.145.1 Synopsis

Function for selecting the spins contained in a file.

10.2.145.2 Defaults

select.
[0]read
(
[0]self, file=
[0]None, dir=
[0]None, spin_id_col=
[0]None, mol_name_col=
[0]None, res_num_col=
[0]None, res_name_col=
[0]None, spin_num_col=
[0]None, spin_name_col=
[0]None, sep=
[0]None, spin_id=
[0]None, boolean=
[0]`OR', change_all=
[0]False)

10.2.145.3 Keyword Arguments

file: The name of the file containing the list of spins to select.

dir: The directory where the file is located.

spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).

mol_name_col: The molecule name column (alternative to the spin_id_col).

res_num_col: The residue number column (alternative to the spin_id_col).

res_name_col: The residue name column (alternative to the spin_id_col).

spin_num_col: The spin number column (alternative to the spin_id_col).

spin_name_col: The spin name column (alternative to the spin_id_col).

data_col: The RDC data column.

error_col: The experimental error column.

sep: The column separator (the default is white space).

spin_id: The spin ID string to restrict the loading of data to certain spin subsets.

boolean: The boolean operator specifying how spins should be selected.

change_all: A flag specifying if all other spins should be changed.

10.2.145.4 Description

The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.

Empty lines and lines beginning with a hash are ignored.

The `change_all' flag argument default is False meaning that all spins currently either selected or deselected will remain that way. Setting the argument to True will cause all spins not specified in the file to be deselected.

10.2.145.5 Examples

To select all residues listed with residue numbers in the first column of the file `isolated_peaks', type one of:


relax> select.
[0]
[0]read(
[0]
[0]`isolated_peaks', res_num_col=
[0]
[0]1)


relax> select.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`isolated_peaks', res_num_col=
[0]
[0]1)

To select the spins in the second column of the relaxation data file `r1.600' while deselecting all other spins, for example type:


relax> select.
[0]
[0]read(
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)


relax> select.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`r1.600', spin_num_col=
[0]
[0]2, change_all=
[0]
[0]True)

10.2.145.6 Boolean operators

The `boolean' keyword argument can be used to change how spin systems are selected. The allowed values are: `OR', `NOR', `AND', `NAND', `XOR', `XNOR'. The following table details how the selections will occur for the different boolean operators.

(see table 10.22)

Table: First table for the select.read() user function.
Spin system 1 2 3 4 5 6 7 8 9
Original selection 0 1 1 1 1 0 1 0 1
New selection 0 1 1 1 1 1 0 0 0
OR 0 1 1 1 1 1 1 0 1
NOR 1 0 0 0 0 0 0 1 0
AND 0 1 1 1 1 0 0 0 0
NAND 1 0 0 0 0 1 1 1 1
XOR 0 0 0 0 0 1 1 0 1
XNOR 1 1 1 1 1 0 0 1 0





10.2.146 select.reverse()

10.2.146.1 Synopsis

Function for the reversal of the spin selection for the given spins.

10.2.146.2 Defaults

select.
[0]reverse
(
[0]self, spin_id=
[0]None)

10.2.146.3 Keyword Arguments

spin_id: The spin identification string.

10.2.146.4 Description

By supplying the spin_id argument, a subset of spin can have their selection status reversed.

10.2.146.5 Examples

To select all currently deselected spins and deselect those which are selected type:


relax> select.
[0]
[0]reverse(
[0]
[0])





10.2.147 select.spin()

10.2.147.1 Synopsis

Function for selecting specific spins.

10.2.147.2 Defaults

select.
[0]spin
(
[0]self, spin_id=
[0]None, boolean=
[0]`OR', change_all=
[0]False)

10.2.147.3 Keyword Arguments

spin_id: The spin identification string.

boolean: The boolean operator specifying how spins should be selected.

change_all: A flag specifying if all other spins should be changed.

10.2.147.4 Description

The `change_all' flag argument default is False meaning that all spins currently either selected or deselected will remain that way. Setting the argument to True will cause all spins not specified by `spin_id' to be selected.

10.2.147.5 Examples

To select only glycines and alanines, assuming they have been loaded with the names GLY and ALA, type one of:


relax> select.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:GLY|:ALA')

To select residue 5 CYS in addition to the currently selected residues, type one of:


relax> select.
[0]
[0]spin(
[0]
[0]`:5')


relax> select.
[0]
[0]spin(
[0]
[0]`:5&:CYS')


relax> select.
[0]
[0]spin(
[0]
[0]spin_id=
[0]
[0]`:5&:CYS')






10.2.148 sequence.copy()

10.2.148.1 Synopsis

Copy the molecule, residue, and spin sequence data from one data pipe to another.

10.2.148.2 Defaults

sequence.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, pipe_to=
[0]None)

10.2.148.3 Keyword Arguments

pipe_from: The name of the data pipe to copy the sequence data from.

pipe_to: The name of the data pipe to copy the sequence data to.

10.2.148.4 Description

This function will copy the sequence data between data pipes. The destination data pipe must not contain any sequence data. If the pipe_from or pipe_to arguments are not supplied, then both will default to the current data pipe (hence giving one argument is essential).

10.2.148.5 Examples

To copy the sequence from the data pipe `m1' to the current data pipe, type:


relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]`m1')


relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1')

To copy the sequence from the current data pipe to the data pipe `m9', type:


relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]pipe_to=
[0]
[0]`m9')

To copy the sequence from the data pipe `m1' to `m2', type:


relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2')


relax> sequence.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', pipe_to=
[0]
[0]`m2')






10.2.149 sequence.display()

10.2.149.1 Synopsis

Function for displaying sequences of molecules, residues, and/or spins.

10.2.149.2 Defaults

sequence.
[0]
[0]display
(
[0]self, sep=
[0]None, mol_name_flag=
[0]True, res_num_flag=
[0]True, res_name_flag=
[0]True, spin_num_flag=
[0]True, spin_name_flag=
[0]True)

10.2.149.3 Keyword Arguments

sep: The column separator (the default of None corresponds to white space).

mol_name_flag: A flag whic if True will cause the molecule name column to be shown.

res_num_flag: A flag whic if True will cause the residue number column to be shown.

res_name_flag: A flag whic if True will cause the residue name column to be shown.

spin_num_flag: A flag whic if True will cause the spin number column to be shown.

spin_name_flag: A flag whic if True will cause the spin name column to be shown.






10.2.150 sequence.read()

10.2.150.1 Synopsis

Read the molecule, residue, and spin sequence from a file.

10.2.150.2 Defaults

sequence.
[0]read
(
[0]self, file=
[0]None, dir=
[0]None, spin_id_col=
[0]None, mol_name_col=
[0]None, res_num_col=
[0]None, res_name_col=
[0]None, spin_num_col=
[0]None, spin_name_col=
[0]None, sep=
[0]None, spin_id=
[0]None)

10.2.150.3 Keyword Arguments

file: The name of the file containing the sequence data.

dir: The directory where the file is located.

spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).

mol_name_col: The molecule name column (alternative to the spin_id_col).

res_num_col: The residue number column (alternative to the spin_id_col).

res_name_col: The residue name column (alternative to the spin_id_col).

spin_num_col: The spin number column (alternative to the spin_id_col).

spin_name_col: The spin name column (alternative to the spin_id_col).

sep: The column separator (the default is white space).

spin_id: The spin ID string to restrict the loading of data to certain spin subsets.

10.2.150.4 Description

The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.

10.2.150.5 Examples

The following commands will read protein backbone 15N sequence data out of a file called `seq' where the residue numbers and names are in the first and second columns respectively:


relax> sequence.
[0]
[0]read(
[0]
[0]`seq')


relax> sequence.
[0]
[0]read(
[0]
[0]`seq', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2)


relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`seq', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, sep=
[0]
[0]None)

The following commands will read the residue sequence out of the file `noe.out' which also contains the NOE values:


relax> sequence.
[0]
[0]read(
[0]
[0]`noe.
[0]
[0]out')


relax> sequence.
[0]
[0]read(
[0]
[0]`noe.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2)


relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`noe.
[0]
[0]out', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2)

The following commands will read the sequence out of the file `noe.600.out' where the residue numbers are in the second column, the names are in the sixth column and the columns are separated by commas:


relax> sequence.
[0]
[0]read(
[0]
[0]`noe.600.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]6, sep=
[0]
[0]`,')


relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`noe.600.
[0]
[0]out', res_num_col=
[0]
[0]2, res_name_col=
[0]
[0]6, sep=
[0]
[0]`,')

The following commands will read the RNA residues and atoms (including C2, C5, C6, C8, N1, and N3) from the file `500.NOE', where the residue number, residue name, spin number, and spin name are in the first to fourth columns respectively:


relax> sequence.
[0]
[0]read(
[0]
[0]`500.
[0]
[0]NOE', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, spin_num_col=
[0]
[0]3, spin_name_col=
[0]
[0]4)


relax> sequence.
[0]
[0]read(
[0]
[0]file=
[0]
[0]`500.
[0]
[0]NOE', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, spin_num_col=
[0]
[0]3, spin_name_col=
[0]
[0]4)






10.2.151 sequence.write()

10.2.151.1 Synopsis

Write the molecule, residue, and spin sequence to a file.

10.2.151.2 Defaults

sequence.
[0]write
(
[0]self, file, dir=
[0]None, sep=
[0]None, mol_name_flag=
[0]False, res_num_flag=
[0]False, res_name_flag=
[0]False, spin_num_flag=
[0]False, spin_name_flag=
[0]False, force=
[0]False)

10.2.151.3 Keyword Arguments

file: The name of the file.

dir: The directory name.

sep: The column separator (the default of None corresponds to white space).

mol_name_flag: A flag whic if True will cause the molecule name column to be shown.

res_num_flag: A flag whic if True will cause the residue number column to be shown.

res_name_flag: A flag whic if True will cause the residue name column to be shown.

spin_num_flag: A flag whic if True will cause the spin number column to be shown.

spin_name_flag: A flag whic if True will cause the spin name column to be shown.

force: A flag which if True will cause the file to be overwritten.

10.2.151.4 Description

If no directory name is given, the file will be placed in the current working directory.





10.2.152 spectrum.baseplane_rmsd()

10.2.152.1 Synopsis

Set the baseplane RMSD of a given spin in a spectrum for error analysis.

10.2.152.2 Defaults

spectrum.
[0]
[0]baseplane_rmsd
(
[0]self, error=
[0]0.0, spectrum_id=
[0]None, spin_id=
[0]None)

10.2.152.3 Keyword Arguments

error: The baseplane RMSD error value.

spectrum_id: The spectrum identification string.

spin_id: The spin identification string.

10.2.152.4 Description

The spectrum_id argument identifies the spectrum associated with the error and must correspond to a previously loaded set of intensities. If the `spin_id' argument is left on the default of None, then the error value for all spins will be set to the supplied value.





10.2.153 spectrum.error_analysis()

10.2.153.1 Synopsis

Function for performing an error analysis for peak intensities.

10.2.153.2 Defaults

spectrum.
[0]
[0]error_analysis
(
[0]self)

10.2.153.3 Description

This user function must only be called after all peak intensities have been loaded and all other necessary spectral information set. This includes the baseplane RMSD and the number of points used in volume integration, both of which are only used if spectra have not been replicated.

Six different types of error analysis are supported depending on whether peak heights or volumes are supplied, whether noise is determined from replicated spectra or the RMSD of the baseplane noise, and whether all spectra or only a subset have been duplicated. These are:

(see table 10.23)

Table: First table for the spectrum.error_analysis() user function.
Int type Noise source Error scope
Heights RMSD baseplane One sigma per peak per spectrum
Heights Partial duplicate + variance averaging One sigma for all peaks, all spectra
Heights All replicated + variance averaging One sigma per replicated spectra set
Volumes RMSD baseplane One sigma per peak per spectrum
Volumes Partial duplicate + variance averaging One sigma for all peaks, all spectra
Volumes All replicated + variance averaging One sigma per replicated spectra set

10.2.153.4 Peak heights with baseplane noise RMSD

When none of the spectra have been replicated, then the peak height errors are calculated using the RMSD of the baseplane noise, the value of which is set by the spectrum.baseplane_rmsd() user function. This results in a different error per peak per spectrum. The standard deviation error measure for the peak height, sigma_I, is set to the RMSD value.

10.2.153.5 Peak heights with partially replicated spectra

When spectra are replicated, the variance for a single spin at a single replicated spectra set is calculated by the formula

 
  
     sigma^2 =  sum({Ii - Iav}^2) / (n - 1) ,

where sigma^2 is the variance, sigma is the standard deviation, $ n$ is the size of the replicated spectra set with $ i$ being the corresponding index, Ii is the peak intensity for spectrum $ i$ , and Iav is the mean over all spectra $ i$ .e. the sum of all peak intensities divided by $ n$ .

As the value of $ n$ in the above equation is always very low since normally only a couple of spectra are collected per replicated spectra set, the variance of all spins is averaged for a single replicated spectra set. Although this results in all spins having the same error, the accuracy of the error estimate is significantly improved.

If there are in addition to the replicated spectra loaded peak intensities which only consist of a single spectrum, $ i$ .e. not all spectra are replicated, then the variances of replicated replicated spectra sets will be averaged. This will be used for the entire experiment so that there will be only a single error value for all spins and for all spectra.

10.2.153.6 Peak heights with all spectra replicated

If all spectra are collected in duplicate (triplicate or higher number of spectra are supported), the each replicated spectra set will have its own error estimate. The error for a single peak is calculated as when partially replicated spectra are collected, and these are again averaged to give a single error per replicated spectra set. However as all replicated spectra sets will have their own error estimate, variance averaging across all spectra sets will not be performed.

10.2.153.7 Peak volumes with baseplane noise RMSD

The method of error analysis when no spectra have been replicated and peak volumes are used is highly dependent on the integration method. Many methods simply sum the number of points within a fixed region, either a box or oval object. The number of points used, N, must be specified by another user function in this class. Then the error is simply given by the sum of variances:

 
  
     sigma_vol^2 = sigma_i^2 * N,

where sigma_vol is the standard deviation of the volume, sigma_i is the standard deviation of a single point assumed to be equal to the RMSD of the baseplane noise, and N is the total number of points used in the summation integration method. For a box integration method, this converts to the Nicholson, Kay, Baldisseri, Arango, Young, Bax, and Torchia (1992) Biochemistry, 31: 5253-5263 equation:

 
  
     sigma_vol = sigma_i * sqrt(n*m),

where $ n$ and $ m$ are the dimensions of the box. Note that a number of programs, for example peakint (http://hugin.ethz.ch/wuthrich/software/xeasy/xeasy_m15.html) does not use all points within the box. And if the number N can not be determined, this category of error analysis is not possible.

Also note that non-point summation methods, for example when line shape fitting is used to determine peak volumes, the equations above cannot be used. Hence again this category of error analysis cannot be used. This is the case for one of the three integration methods used by Sparky (http://www.cgl.ucsf.edu/home/sparky/manual/peaks.html#Integration). And if fancy techniques are used, for example as Cara does to deconvolute overlapping peaks (http://www.cara.ethz.ch/Wiki/Integration), this again makes this error analysis impossible.

10.2.153.8 Peak volumes with partially replicated spectra

When peak volumes are measured by any integration method and a few of the spectra are replicated, then the intensity errors are calculated identically as described in the `Peak heights with partially replicated spectra' section above.

10.2.153.9 Peak volumes with all spectra replicated

With all spectra replicated and again using any integration methodology, the intensity errors can be calculated as described in the `Peak heights with all spectra replicated' section above.





10.2.154 spectrum.integration_points()

10.2.154.1 Synopsis

Set the number of summed points used in volume integration of a given spin in a spectrum.

10.2.154.2 Defaults

spectrum.
[0]
[0]integration_points
(
[0]self, N=
[0]None, spectrum_id=
[0]None, spin_id=
[0]None)

10.2.154.3 Keyword Arguments

N: The number of points used by the summation volume integration method.

spectrum_id: The spectrum identification string.

spin_id: The spin identification string.

10.2.154.4 Description

For a complete description of which integration methods and how many points N are used for different integration techniques, please read the spectrum.error_analysis() documentation.

The spectrum_id argument identifies the spectrum associated with the value of N and must correspond to a previously loaded set of intensities. If the `spin_id' argument is left on the default of None, then the number of summed points for all spins will be set to the supplied value.





10.2.155 spectrum.read_intensities()

10.2.155.1 Synopsis

Function for reading peak intensities from a file for NOE calculations.

10.2.155.2 Defaults

spectrum.
[0]read_intensities
(
[0]self, file=
[0]None, dir=
[0]None, spectrum_id=
[0]None, heteronuc=
[0]`N', proton=
[0]`HN', int_col=
[0]None, int_method=
[0]`height', spin_id_col=
[0]None, mol_name_col=
[0]None, res_num_col=
[0]None, res_name_col=
[0]None, spin_num_col=
[0]None, spin_name_col=
[0]None, sep=
[0]None, spin_id=
[0]None, ncproc=
[0]None)

10.2.155.3 Keyword Arguments

file: The name of the file containing the intensity data.

dir: The directory where the file is located.

spectrum_id: The spectrum identification string.

heteronuc: The name of the heteronucleus as specified in the peak intensity file.

proton: The name of the proton as specified in the peak intensity file.

int_col: The column containing the peak intensity data (used by the generic intensity file format).

int_method: The integration method.

spin_id_col: The spin ID string column used by the generic intensity file format (an alternative to the mol, res, and spin name and number columns).

mol_name_col: The molecule name column used by the generic intensity file format (alternative to the spin_id_col).

res_num_col: The residue number column used by the generic intensity file format (alternative to the spin_id_col).

res_name_col: The residue name column used by the generic intensity file format (alternative to the spin_id_col).

spin_num_col: The spin number column used by the generic intensity file format (alternative to the spin_id_col).

spin_name_col: The spin name column used by the generic intensity file format (alternative to the spin_id_col).

sep: The column separator used by the generic intensity format (the default is white space).

spin_id: The spin ID string used by the generic intensity file format to restrict the loading of data to certain spin subsets.

ncproc: The Bruker specific FID intensity scaling factor.

10.2.155.4 Description

The peak intensity can either be from peak heights or peak volumes.

The `spectrum_id' argument is a label which is subsequently utilised by other user functions. If this identifier matches that of a previously loaded set of intensities, then this indicates a replicated spectrum.

The `heteronuc' and `proton' arguments should be set respectively to the name of the heteronucleus and proton in the file. Only those lines which match these labels will be used.

The `int_method' argument is required for the subsequent error analysis. When peak heights are measured, this argument should be set to `height'. Volume integration methods are a bit varied and hence two values are accepted. If the volume integration involves pure point summation, with no deconvolution algorithms or other methods affecting peak heights, then the argument should be set to `point sum'. All other volume integration methods, e.g. line shape fitting, the argument should be set to `other'.

If a series of intensities extracted from Bruker FID files processed in Topspin or XWinNMR are to be compared, the ncproc parameter may need to be supplied. This is because this FID is stored using integer representation and is scaled using ncproc to avoid numerical truncation artifacts. If two spectra have significantly different maximal intensities, then ncproc will be different for both. The intensity scaling is binary, $ i$ .e. 2**ncproc. Therefore if spectrum A has an ncproc of 6 and and spectrum B a value of 7, then a reference intensity in B will be double that of A. Internally, relax stores the intensities scaled by 2**ncproc.

10.2.155.5 File formats

The peak list or intensity file will be automatically determined.

Sparky peak list: The file should be a Sparky peak list saved after typing the command `lt'. The default is to assume that columns 0, 1, 2, and 3 (1 $ ^\mathrm{st}$ , 2 $ ^\mathrm{nd}$ , 3 $ ^\mathrm{rd}$ , and 4 $ ^\mathrm{th}$ ) contain the Sparky assignment, w1, w2, and peak intensity data respectively. The frequency data w1 and w2 are ignored while the peak intensity data can either be the peak height or volume displayed by changing the window options. If the peak intensity data is not within column 3, set the argument `int_col' to the appropriate value (column numbering starts from 0 rather than 1).

XEasy peak list: The file should be the saved XEasy text window output of the list peak entries command, `tw' followed by `le'. As the columns are fixed, the peak intensity column is hardwired to number 10 (the 11 $ ^\mathrm{th}$ column) which contains either the peak height or peak volume data. Because the columns are fixed, the `int_col' argument will be ignored.

NMRView: The file should be a NMRView peak list. The default is to use column 16 (which contains peak heights) for peak intensities. To use use peak volumes (or evolumes), int_col must be set to 15.

Generic intensity file: This is a generic format which can be created by scripting to support non-supported peak lists. It should contain in the first few columns enough information to identify the spin. This can include columns for the molecule name, residue number, residue name, spin number, and spin name, with each optional type positioned with the *name_col and *num_col arguments. Alternatively a spin ID string column can be used. The peak intensities can be placed in another column specified by the int_col argument. Intensities from multiple spectra can be placed into different columns, and these can then be specified simultaneously by setting the int_col argument to a list of columns. This list must be matched by setting the spectrum_id argument to list of the same length. If columns are delimited by a character other than whitespace, this can be specified with the sep argument. The spin_id argument can be used to restrict the loading to specific spin subsets.

10.2.155.6 Examples

To read the reference and saturated spectra peak heights from the Sparky formatted files `ref.list' and `sat.list', type:


relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`ref.
[0]
[0]list', spectrum_id=
[0]
[0]`ref')


relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`sat.
[0]
[0]list', spectrum_id=
[0]
[0]`sat')

To read the reference and saturated spectra peak heights from the XEasy formatted files `ref.text' and `sat.text', type:


relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`ref.
[0]
[0]text', spectrum_id=
[0]
[0]`ref')


relax> spectrum.
[0]
[0]read_intensities(
[0]
[0]file=
[0]
[0]`sat.
[0]
[0]text', spectrum_id=
[0]
[0]`sat')





10.2.156 spectrum.replicated()

10.2.156.1 Synopsis

Function for specifying which spectra are replicates.

10.2.156.2 Defaults

spectrum.
[0]replicated
(
[0]self, spectrum_ids=
[0]None)

10.2.156.3 Keyword Arguments

spectrum_ids: The list of replicated spectra identification strings.

10.2.156.4 Description

This user function is used to identify which loaded spectra are replicates of each other. This is very important for error analysis.

10.2.156.5 Examples

To specify that the NOE spectra labelled `ref1', `ref2', and `ref3' are the same spectrum replicated, type one of:


relax> spectrum.
[0]
[0]replicated(
[0]
[0][`ref1', `ref2', `ref3'])


relax> spectrum.
[0]
[0]replicated(
[0]
[0]spectrum_ids=
[0]
[0][`ref1', `ref2', `ref3'])

To specify that the two R$ _2$ spectra `ncyc2' and `ncyc2$ b$ ' are the same time point, type:


relax> spectrum.
[0]
[0]replicated(
[0]
[0][`ncyc2', `ncyc2b'])





10.2.157 spin.copy()

10.2.157.1 Synopsis

Function for copying all data associated with a spin.

10.2.157.2 Defaults

spin.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, spin_from=
[0]None, pipe_to=
[0]None, spin_to=
[0]None)

10.2.157.3 Keyword Arguments

pipe_from: The data pipe containing the spin from which the data will be copied. This defaults to the current data pipe.

spin_from: The spin identifier string of the spin to copy the data from.

pipe_to: The data pipe to copy the data to. This defaults to the current data pipe.

spin_to: The spin identifier string of the spin to copy the data to.

10.2.157.4 Description

This function will copy all the data associated with the identified spin to the new, non-existent spin. The new spin must not already exist.

10.2.157.5 Examples

To copy the spin data from spin 1 to the new spin 2, type:


relax> spin.
[0]
[0]
[0]copy(
[0]
[0]spin_from=
[0]
[0]`@1', spin_to=
[0]
[0]`@2')

To copy spin 1 of the molecule `Old mol' to spin 5 of the molecule `New mol', type:


relax> spin.
[0]
[0]
[0]copy(
[0]
[0]spin_from=
[0]
[0]`#Old mol@1', spin_to=
[0]
[0]`#New mol@5')

To copy the spin data of spin 1 from the data pipe `m1' to `m2', assuming the current data pipe is `m1', type:


relax> spin.
[0]
[0]
[0]copy(
[0]
[0]spin_from=
[0]
[0]`@1', pipe_to=
[0]
[0]`m2')


relax> spin.
[0]
[0]
[0]copy(
[0]
[0]pipe_from=
[0]
[0]`m1', spin_from=
[0]
[0]`@1', pipe_to=
[0]
[0]`m2', spin_to=
[0]
[0]`@1')

10.2.157.6 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.158 spin.create()

10.2.158.1 Synopsis

Function for creating a new spin.

10.2.158.2 Defaults

spin.
[0]
[0]create
(
[0]self, spin_num=
[0]None, spin_name=
[0]None, res_num=
[0]None, res_name=
[0]None, mol_name=
[0]None)

10.2.158.3 Keyword Arguments

spin_num: The spin number.

spin_name: The name of the spin.

res_num: The number of the residue to add the spin to.

res_name: The name of the residue to add the spin to.

mol_name: The name of the molecule to add the spin to.

10.2.158.4 Description

This function will add a new spin data container to the relax data storage object. The same spin number cannot be used more than once.

10.2.158.5 Examples

The following sequence of commands will generate the sequence 1 C4, 2 C9, 3 C15:


relax> spin.
[0]
[0]
[0]create(
[0]
[0]1, `C4')


relax> spin.
[0]
[0]
[0]create(
[0]
[0]2, `C9')


relax> spin.
[0]
[0]
[0]create(
[0]
[0]3, `C15')

10.2.158.6 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.159 spin.create_pseudo()

10.2.159.1 Synopsis

Function for creating a spin system representing a pseudo-atom.

10.2.159.2 Defaults

spin.
[0]
[0]create_pseudo
(
[0]self, spin_name=
[0]None, spin_num=
[0]None, res_id=
[0]None, members=
[0]None, averaging=
[0]`linear')

10.2.159.3 Keyword Arguments

spin_name: The name of the pseudo-atom spin.

spin_num: The spin number.

res_id: The molecule and residue ID string identifying the position to add the pseudo-spin to.

mol_id: The molecule ID string identifying the molecule to add the pseudo-spin to.

members: A list of the atoms the pseudo-atom is composed of.

averaging: The positional averaging technique.

10.2.159.4 Description

This function will create a spin data container representing a number of pre-existing spin containers as a pseudo-atom. The optional spin number must not already exist.

10.2.159.5 Examples

The following will create the pseudo-atom named `Q9' consisting of the protons `@H16', `@H17', `@H18':


relax> spin.
[0]
[0]
[0]create_pseudo(
[0]
[0]`Q9', members=
[0]
[0][`@H16', `@H17', `@H18'])





10.2.160 spin.delete()

10.2.160.1 Synopsis

Function for deleting spins.

10.2.160.2 Defaults

spin.
[0]
[0]delete
(
[0]self, spin_id=
[0]None)

10.2.160.3 Keyword Arguments

spin_id: The spin identifier string.

10.2.160.4 Description

This function can be used to delete a single or sets of spins. See the identification string documentation below for more information.

10.2.160.5 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.161 spin.display()

10.2.161.1 Synopsis

Function for displaying information about the spin(s).

10.2.161.2 Defaults

spin.
[0]
[0]display
(
[0]self, spin_id=
[0]None)

10.2.161.3 Keyword Arguments

spin_id: The spin identification string.

10.2.161.4 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.162 spin.element()

10.2.162.1 Synopsis

Set the element type of the spin.

10.2.162.2 Defaults

spin.
[0]
[0]element
(
[0]self, spin_id=
[0]None, element=
[0]None, force=
[0]False)

10.2.162.3 Keyword Arguments

spin_id: The spin identification string corresponding to one or more spins.

element: The IUPAC element name.

force: A flag which if True will cause the element to be changed.

10.2.162.4 Description

This function allows the element type of the spins to be set.

10.2.162.5 Examples

The set all spins of residue 1 to be carbons, type one of:


relax> spin.
[0]
[0]
[0]element(
[0]
[0]`@1', `C', force=
[0]
[0]True)


relax> spin.
[0]
[0]
[0]element(
[0]
[0]spin_id=
[0]
[0]`@1', element=
[0]
[0]`C', force=
[0]
[0]True)





10.2.163 spin.name()

10.2.163.1 Synopsis

Function for naming spins.

10.2.163.2 Defaults

spin.
[0]name
(
[0]self, spin_id=
[0]None, name=
[0]None, force=
[0]False)

10.2.163.3 Keyword Arguments

spin_id: The spin identification string corresponding to one or more spins.

name: The new name.

force: A flag which if True will cause the spin to be renamed.

10.2.163.4 Description

This function simply allows spins to be named (or renamed).

10.2.163.5 Examples

The following sequence of commands will rename the sequence {1 C1, 2 C2, 3 C3} to {1 C11, 2 C12, 3 C13}:


relax> spin.
[0]
[0]name(
[0]
[0]`@1', `C11', force=
[0]
[0]True)


relax> spin.
[0]
[0]name(
[0]
[0]`@2', `C12', force=
[0]
[0]True)


relax> spin.
[0]
[0]name(
[0]
[0]`@3', `C13', force=
[0]
[0]True)

10.2.163.6 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.164 spin.number()

10.2.164.1 Synopsis

Function for numbering spins.

10.2.164.2 Defaults

spin.
[0]number
(
[0]self, spin_id=
[0]None, number=
[0]None, force=
[0]False)

10.2.164.3 Keyword Arguments

spin_id: The spin identification string corresponding to a single spin.

number: The new spin number.

force: A flag which if True will cause the spin to be renumbered.

10.2.164.4 Description

This function simply allows spins to be numbered. The new number cannot correspond to an existing spin number.

10.2.164.5 Examples

The following sequence of commands will renumber the sequence {1 C1, 2 C2, 3 C3} to {-1 C1, -2 C2, -3 C3}:


relax> spin.
[0]
[0]number(
[0]
[0]`@1', -1, force=
[0]
[0]True)


relax> spin.
[0]
[0]number(
[0]
[0]`@2', -2, force=
[0]
[0]True)


relax> spin.
[0]
[0]number(
[0]
[0]`@3', -3, force=
[0]
[0]True)

10.2.164.6 Identification string documentation

The identification string is composed of three components: the molecule id token beginning with the `#' character, the residue id token beginning with the `:' character, and the atom or spin system id token beginning with the `@' character. Each token can be composed of multiple elements separated by the `,' character and each individual element can either be a number (which must be an integer, in string format), a name, or a range of numbers separated by the `-' character. Negative numbers are supported. The full id string specification is `#<mol_name> :<res_id>[, <res_id>[, <res_id>, ...]] @<atom_id>[, <atom_id>[, <atom_id>, ...]]', where the token elements are `<mol_name>', the name of the molecule, `<res_id>', the residue identifier which can be a number, name, or range of numbers, `<atom_id>', the atom or spin system identifier which can be a number, name, or range of numbers.

If one of the tokens is left out then all elements will be assumed to match. For example if the string does not contain the `#' character then all molecules will match the string.

Regular expression can be used to select spins. For example the string `@H*' will select the protons `H', `H2', `H98'.





10.2.165 state.load()

10.2.165.1 Synopsis

Function for loading a saved program state.

10.2.165.2 Defaults

state.
[0]load
(
[0]self, state=
[0]None, dir=
[0]None, force=
[0]False)

10.2.165.3 Keyword Arguments

state: The file name, which can be a string or a file descriptor object, of a saved program state.

dir: The name of the directory in which the file is found.

force: A boolean flag which if True will cause the current program state to be overwritten.

10.2.165.4 Description

This function is able to handle uncompressed, bzip2 compressed files, or gzip compressed files automatically. The full file name including extension can be supplied, however, if the file cannot be found, this function will search for the file name with `.bz2' appended followed by the file name with `.gz' appended.

Both the XML and pickled saved state formats are supported and automatically determined. For more advanced users, file descriptor objects are also supported. If the force flag is set to True, then the relax data store will be reset prior to the loading of the saved state.

10.2.165.5 Examples

The following commands will load the state saved in the file `save'.


relax> state.
[0]
[0]load(
[0]
[0]`save')


relax> state.
[0]
[0]load(
[0]
[0]state=
[0]
[0]`save')

Use one of the following commands to load the state saved in the bzip2 compressed file `save.bz2':


relax> state.
[0]
[0]load(
[0]
[0]`save')


relax> state.
[0]
[0]load(
[0]
[0]state=
[0]
[0]`save')


relax> state.
[0]
[0]load(
[0]
[0]`save.
[0]
[0]
[0]bz2')


relax> state.
[0]
[0]load(
[0]
[0]state=
[0]
[0]`save.
[0]
[0]
[0]bz2', force=
[0]
[0]True)





10.2.166 state.save()

10.2.166.1 Synopsis

Function for saving the program state.

10.2.166.2 Defaults

state.
[0]save
(
[0]self, state=
[0]None, dir=
[0]None, compress_type=
[0]1, force=
[0]False, pickle=
[0]False)

10.2.166.3 Keyword Arguments

state: The file name, which can be a string or a file descriptor object, to save the current program state in.

dir: The name of the directory in which to place the file.

compress_type: The type of compression to use when creating the file.

force: A boolean flag which if set to True will cause the file to be overwritten.

pickle: A flag which if true will cause the state file to be a pickled object rather than the default XML format.

10.2.166.4 Description

This user function will place the program state - the relax data store - into a file for later reloading or reference. The default format is an XML formatted file, but this can be changed to a Python pickled object through the pickle flag. Note, the pickle format is not human readable and often is not compatible with newer relax versions.

The default behaviour of this function is to compress the file using bzip2 compression. If the extension `.bz2' is not included in the file name, it will be added. The compression can, however, be changed to either no compression or gzip compression. This is controlled by the compress_type argument which can be set to

0 -
No compression (no file extension).
1 -
bzip2 compression (`.bz2' file extension).
2 -
gzip compression (`.gz' file extension).

10.2.166.5 Examples

The following commands will save the current program state, uncompressed, into the file `save':


relax> state.
[0]
[0]save(
[0]
[0]`save', compress_type=
[0]
[0]0)


relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save', compress_type=
[0]
[0]0)

The following commands will save the current program state into the bzip2 compressed file `save.bz2':


relax> state.
[0]
[0]save(
[0]
[0]`save')


relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save')


relax> state.
[0]
[0]save(
[0]
[0]`save.
[0]
[0]
[0]bz2')


relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save.
[0]
[0]
[0]bz2')

If the file `save' already exists, the following commands will save the current program state by overwriting the file.


relax> state.
[0]
[0]save(
[0]
[0]`save', force=
[0]
[0]True)


relax> state.
[0]
[0]save(
[0]
[0]state=
[0]
[0]`save', force=
[0]
[0]True)





10.2.167 structure.create_diff_tensor_pdb()

10.2.167.1 Synopsis

Create a PDB file to represent the diffusion tensor.

10.2.167.2 Defaults

structure.
[0]
[0]create_diff_tensor_pdb
(
[0]self, scale=
[0]1.7999999999999999e-06, file=
[0]`tensor.
[0]pdb', dir=
[0]None, force=
[0]False)

10.2.167.3 Keyword Arguments

scale: Value for scaling the diffusion rates.

file: The name of the PDB file.

dir: The directory where the file is located.

force: A flag which, if set to True, will overwrite the any pre-existing file.

10.2.167.4 Description

This function creates a PDB file containing an artificial geometric structure to represent the diffusion tensor. A structure must have previously been read into relax. The diffusion tensor is represented by an ellipsoidal, spheroidal, or spherical geometric object with its origin located at the centre of mass (of the selected residues). This diffusion tensor PDB file can subsequently read into any molecular viewer.

There are four different types of residue within the PDB. The centre of mass of the selected residues is represented as a single carbon atom of the residue `COM'. The ellipsoidal geometric shape consists of numerous H atoms of the residue `TNS'. The axes of the tensor, when defined, are presented as the residue `AXS' and consist of carbon atoms: one at the centre of mass and one at the end of each eigenvector. Finally, if Monte Carlo simulations were run and the diffusion tensor parameters were allowed to vary then there will be multiple `SIM' residues, one for each simulation. These are essentially the same as the `AXS' residue, representing the axes of the simulated tensors, and they will appear as a distribution.

As the Brownian rotational diffusion tensor is a measure of the rate of rotation about different axes - the larger the geometric object, the faster the diffusion of a molecule. For example the diffusion tensor of a water molecule is much larger than that of a macromolecule.

The effective global correlation time experienced by an XH bond vector, not to be confused with the Lipari and Szabo parameter $ \tau$ _e, will be approximately proportional to the component of the diffusion tensor parallel to it. The approximation is not exact due to the multiexponential form of the correlation function of Brownian rotational diffusion. If an XH bond vector is parallel to the longest axis of the tensor, it will be unaffected by rotations about that axis, which are the fastest rotations of the molecule, and therefore its effective global correlation time will be maximal.

To set the size of the diffusion tensor within the PDB frame the unit vectors used to generate the geometric object are first multiplied by the diffusion tensor (which has the units of inverse seconds) then by the scaling factor (which has the units of second Åand has the default value of 1.8e-6 s.Angstrom). Therefore the rotational diffusion rate per Åis equal the inverse of the scale value (which defaults to 5.56e5 s^-1.Angstrom^-1). Using the default scaling value for spherical diffusion, the correspondence between global correlation time, $ \mathfrak{D}_{iso}$ diffusion rate, and the radius of the sphere for a number of discrete cases will be:

(see table 10.24)

Table: First table for the structure.create_diff_tensor_pdb() user function.
$ \tau _m$ (ns) $ \mathfrak{D}_{iso}$ (s^-1) Radius (Å)
1 1.67e8 300
3 5.56e7 100
10 1.67e7 30
30 5.56e6 10

The scaling value has been fixed to facilitate comparisons within or between publications, but can be changed to vary the size of the tensor geometric object if necessary. Reporting the rotational diffusion rate per Åwithin figure legends would be useful.

To create the tensor PDB representation, a number of algorithms are utilised. Firstly the centre of mass is calculated for the selected residues and is represented in the PDB by a C atom. Then the axes of the diffusion are calculated, as unit vectors scaled to the appropriate length (multiplied by the eigenvalue $ \mathfrak{D}_x$ , $ \mathfrak{D}_y$ , $ \mathfrak{D}_z$ , $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ , $ \mathfrak{D}_{\scriptscriptstyle \perp}$ , or $ \mathfrak{D}_{iso}$ as well as the scale value), and a C atom placed at the position of this vector plus the centre of mass. Finally a uniform distribution of vectors on a sphere is generated using spherical coordinates. By incrementing the polar angle using an arccos distribution, a radial array of vectors representing latitude are created while incrementing the azimuthal angle evenly creates the longitudinal vectors. These unit vectors, which are distributed within the PDB frame and are of 1 Åin length, are first rotated into the diffusion frame using a rotation matrix (the spherical diffusion tensor is not rotated). Then they are multiplied by the diffusion tensor matrix to extend the vector out to the correct length, and finally multiplied by the scale value so that the vectors reasonably superimpose onto the macromolecular structure. The last set of algorithms place all this information into a PDB file. The distribution of vectors are represented by H atoms and are all connected using PDB CONECT records. Each H atom is connected to its two neighbours on the both the longitude and latitude. This creates a geometric PDB object with longitudinal and latitudinal lines.





10.2.168 structure.create_vector_dist()

10.2.168.1 Synopsis

Create a PDB file representation of the distribution of XH bond vectors.

10.2.168.2 Defaults

structure.
[0]
[0]create_vector_dist
(
[0]self, length=
[0]2.0000000000000001e-09, file=
[0]`XH_dist.
[0]pdb', dir=
[0]None, symmetry=
[0]True, force=
[0]False)

10.2.168.3 Keyword Arguments

length: The length of the vectors in the PDB representation (meters).

file: The name of the PDB file.

dir: The directory to place the file into.

symmetry: A flag which if True will create a second chain with reversed XH bond orientations.

force: A flag which if True will overwrite the file if it already exists.

10.2.168.4 Description

This function creates a PDB file containing an artificial vectors, the length of which default to the length argument of 20 Å. A structure must have previously been read into relax. The origin of the vector distribution is located at the centre of mass (of the selected residues). This vector distribution PDB file can subsequently be read into any molecular viewer.

Because of the symmetry of the diffusion tensor reversing the orientation of the XH bond vector has no effect. Therefore by setting the symmetry flag two chains `A' and `B' will be added to the PDB file whereby chain `B' is chain `A' with the XH bonds reversed.





10.2.169 structure.delete()

10.2.169.1 Synopsis

Delete all structural information from the current data pipe.

10.2.169.2 Defaults

structure.
[0]
[0]delete
(
[0]self)

10.2.169.3 Description

This function will delete all the structural information.

10.2.169.4 Example

Simply type:


relax> structure.
[0]
[0]
[0]delete(
[0]
[0])





10.2.170 structure.get_pos()

10.2.170.1 Synopsis

Extract the atomic positions from the loaded structures for the given spins.

10.2.170.2 Defaults

structure.
[0]
[0]get_pos
(
[0]self, spin_id=
[0]None, ave_pos=
[0]True)

10.2.170.3 Keyword Arguments

spin_id: The spin identification string.

ave_pos: A flag specifying if the position of the atom is to be averaged across models.

10.2.170.4 Description

This function allows the atomic positions of the spins to be extracted from the loaded structures. This is automatically performed by the structure.load_spins() user function, but if the sequence information is generated in other ways, this user function allows the structural information to be obtained.

If the ave_pos flag is True, the average position of all models will be loaded into the spin container. If False, then the positions from all models will be loaded.

10.2.170.5 Example

For a model-free backbone amide nitrogen analysis whereby the N spins have already been created, to obtain the backbone N positions from the file `1F3Y.pdb' (which is a single protein), type the following two user functions:


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`1F3Y.
[0]
[0]pdb')


relax> structure.
[0]
[0]
[0]get_pos(
[0]
[0]spin_id=
[0]
[0]`@N')





10.2.171 structure.load_spins()

10.2.171.1 Synopsis

Load spins from the structure into the relax data store.

10.2.171.2 Defaults

structure.
[0]load_spins
(
[0]self, spin_id=
[0]None, ave_pos=
[0]True)

10.2.171.3 Keyword Arguments

spin_id: The spin identification string.

ave_pos: A flag specifying if the position of the atom is to be averaged across models.

10.2.171.4 Description

This function allows a sequence to be generated within the relax data store using the atomic information from the structure already associated with this data pipe. The spin_id string is used to select which molecules, which residues, and which atoms will be recognised as spin systems within relax. If spin_id is left as None, then all molecules, residues, and atoms will be placed within the data store.

If the ave_pos flag is True, the average position of all models will be loaded into the spin container. If False, then the positions from all models will be loaded.

10.2.171.5 Example

For a model-free backbone amide nitrogen analysis, to load just the backbone N sequence from the file `1F3Y.pdb' (which is a single protein), type the following two user functions:


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`1F3Y.
[0]
[0]pdb')


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]`@N')

For an RNA analysis of adenine C8 and C2, guanine C8 and N1, cytidine C5 and C6, and uracil N3, C5, and C6, type the following series of commands (assuming that the PDB file with this atom naming has already been read):


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":A@C8")


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":A@C2")


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":G@C8")


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":G@N1")


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":C@C5")


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":C@C6")


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":U@N3")


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":U@C5")


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]":U@C6")

Alternatively using some Python programming:


relax> for id in [":A@C8", ":A@C2", ":G@C8", ":G@N1", ":C@C5", ":C@C6", ":U@N3", ":U@C5", ":U@C6"]:


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]id)

Example for xyz file To load all C atoms from the `test.xyz' (which is a single molecule), type the following two user functions:


relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz')


relax> structure.
[0]
[0]load_spins(
[0]
[0]spin_id=
[0]
[0]`@*C*')

To load only the third atom from the xyz file, type the following user function: relax> structure.load_spins(spin_id=`@3')





10.2.172 structure.read_pdb()

10.2.172.1 Synopsis

The PDB loading function.

10.2.172.2 Defaults

structure.
[0]read_pdb
(
[0]self, file=
[0]None, dir=
[0]None, read_mol=
[0]None, set_mol_name=
[0]None, read_model=
[0]None, set_model_num=
[0]None, parser=
[0]`internal')

10.2.172.3 Keyword Arguments

file: The name of the PDB file.

dir: The directory where the file is located.

read_mol: If set, only the given molecule(s) will be read.

set_mol_name: Set the names of the read molecules.

read_model: If set, only the given model number(s) from the PDB file will be read.

set_model_num: Set the model numbers of the read molecules.

parser: The PDB parser used to read the file.

10.2.172.4 Description

The reading of PDB files into relax is quite a flexible procedure allowing for both models, defined as an ensemble of the same molecule but with different atomic positions, and different molecules within the same model. One of more molecules can exist in one or more models. The flexibility allows PDB models to be converted into different molecules and different PDB files loaded as the same molecule but as different models. This flexibility is controlled by the four keyword arguments `read_mol', `set_mol_name', `read_model', and `set_model_num'.

A few different PDB parsers can be used to read the structural data. The choice of which to use depends on whether your PDB file is supported by that reader. These are selected by setting the `parser' argument to one of:

`scientific' - the Scientific Python PDB parser.
`internal' - a lower quality and less reliable, although faster, PDB parser built into
relax.

In a PDB file, the models are specified by the MODEL PDB record. All the supported PDB readers in relax recognise this. The molecule level is quite different between the Scientific Python and internal readers. For how Scientific Python defines molecules, please see its documentation. The internal reader is far simpler as it defines molecules using the TER PDB record. In both cases, the molecules will be numbered consecutively from 1.

The `set_mol_name' argument is used to name the molecules within the PDB (within one model). If not set, then the molecules will be named after the file name, with the molecule number appended if more than one exists.

Note that relax will complain if it cannot work out what to do.

10.2.172.5 Examples

To load all structures from the PDB file `test.pdb' in the directory `~/pdb', including all models and all molecules, type one of:


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', `~/pdb')


relax> structure.
[0]
[0]read_pdb(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]pdb', dir=
[0]
[0]`pdb')

To load the 10 $ ^\mathrm{th}$ model from the file `test.pdb' using the Scientific Python PDB parser and naming it `CaM', use one of:


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM', parser=
[0]
[0]`scientific')


relax> structure.
[0]
[0]read_pdb(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]pdb', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM', parser=
[0]
[0]`scientific')

To load models 1 and 5 from the file `test.pdb' as two different structures of the same model, type one of:


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`test.
[0]
[0]pdb', set_mol_name=
[0]
[0][`CaM_1', `CaM_2'], read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])

To load the files `lactose_MCMM4_S1_1.pdb', `lactose_MCMM4_S1_2.pdb', `lactose_MCMM4_S1_3.pdb' and `lactose_MCMM4_S1_4.pdb' as models, type the following sequence of commands:


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_1.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]1)


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_2.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]2)


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_3.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]3)


relax> structure.
[0]
[0]read_pdb(
[0]
[0]`lactose_MCMM4_S1_4.
[0]
[0]pdb', set_mol_name=
[0]
[0]`lactose_MCMM4_S1', set_model_num=
[0]
[0]4)





10.2.173 structure.read_xyz()

10.2.173.1 Synopsis

The XYZ loading function.

10.2.173.2 Defaults

structure.
[0]read_xyz
(
[0]self, file=
[0]None, dir=
[0]None, read_mol=
[0]None, set_mol_name=
[0]None, read_model=
[0]None, set_model_num=
[0]None)

10.2.173.3 Keyword Arguments

file: The name of the XYZ file.

dir: The directory where the file is located.

read_mol: If set, only the given molecule(s) will be read.

set_mol_name: Set the names of the read molecules.

read_model: If set, only the given model number(s) from the XYZ file will be read.

set_model_num: Set the model numbers of the read molecules.

10.2.173.4 Description

The XYZ files with different models, which defined as an ensemble of the same molecule but with different atomic positions, can be read into relax. If there are several molecules in one xyz file, please seperate them into different files and then load them individually. Loading different models and different molecules is controlled by the four keyword arguments `read_mol', `set_mol_name', `read_model', and `set_model_num'.

The `set_mol_name' argument is used to name the molecules within the XYZ (within one model). If not set, then the molecules will be named after the file name, with the molecule number appended if more than one exists.

Note that relax will complain if it cannot work out what to do.

10.2.173.5 Examples

To load all structures from the XYZ file `test.xyz' in the directory `~/xyz', including all models and all molecules, type one of:


relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', `~/xyz')


relax> structure.
[0]
[0]read_xyz(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]xyz', dir=
[0]
[0]`xyz')

To load the 10 $ ^\mathrm{th}$ model from the file `test.xyz' and naming it `CaM', use one of:


relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM')


relax> structure.
[0]
[0]read_xyz(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]xyz', read_model=
[0]
[0]10, set_mol_name=
[0]
[0]`CaM')

To load models 1 and 5 from the file `test.xyz' as two different structures of the same model, type one of:


relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])


relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test.
[0]
[0]xyz', set_mol_name=
[0]
[0][`CaM_1', `CaM_2'], read_model=
[0]
[0][1, 5], set_model_num=
[0]
[0][1, 1])

To load the files `test_1.xyz', `test_2.xyz', `test_3.xyz' and `test_4.xyz' as models, type the following sequence of commands:


relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_1.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_1', set_model_num=
[0]
[0]1)


relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_2.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_2', set_model_num=
[0]
[0]2)


relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_3.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_3', set_model_num=
[0]
[0]3)


relax> structure.
[0]
[0]read_xyz(
[0]
[0]`test_4.
[0]
[0]xyz', set_mol_name=
[0]
[0]`test_4', set_model_num=
[0]
[0]4)





10.2.174 structure.vectors()

10.2.174.1 Synopsis

Extract and store the bond vectors from the loaded structures in the spin container.

10.2.174.2 Defaults

structure.
[0]vectors
(
[0]self, attached=
[0]`H', spin_id=
[0]None, model=
[0]None, verbosity=
[0]1, ave=
[0]True, unit=
[0]True)

10.2.174.3 Keyword arguments

attached: The name of the second atom which attached to the spin of interest. Regular expression is allowed, for example `H*'.

spin_id: The spin identification string.

model: The model to extract bond vectors from (which if set to None will cause the vectors of all models to be extracted).

verbosity: The amount of information to print to screen. Zero corresponds to minimal output while higher values increase the amount of output. The default value is 1.

ave: A flag which if True will cause the bond vectors from all models to be averaged. If vectors from only one model is extracted, this argument will have no effect.

unit: A flag which if True will cause the unit vector to calculated rather than the full length bond vector.

10.2.174.4 Description

For a number of types of analysis, bond vectors or unit bond vectors are required for the calculations. This user function allows these vectors to be extracted from the loaded structures. The bond vector will be that from the atom associated with the spin system loaded in relax to the bonded atom specified by the `attached' argument. For example if `attached' is set to `H' and the protein backbone amide spins `N' are loaded, the all `N-H' vectors will be extracted. But if set to `CA', all atoms named `CA' in the structures will be searched for and all `N-Ca' bond vectors will be extracted.

The extraction of vectors can occur in a number of ways. For example if an NMR structure with N models is loaded or if multiple molecules, from any source, of the same compound are loaded as different models, there are three options for extracting the bond vector. Firstly the bond vector of a single model can be extracted by setting the `model' argument. Secondly the bond vectors from all models can be extracted if `model' is None and `ave' is set to False. Thirdly, if `model' is None and `ave' is set to True, then a single vector which is the average for all models will be calculated.

10.2.174.5 Example

To extract the XH vectors of the backbone amide nitrogens where in the PDB file the backbone nitrogen is called `N' and the attached atom is called `H', assuming multiple types of spin have already been loaded, type one of:


relax> structure.
[0]
[0]vectors(
[0]
[0]spin_id=
[0]
[0]`@N')


relax> structure.
[0]
[0]vectors(
[0]
[0]`H', spin_id=
[0]
[0]`@N')


relax> structure.
[0]
[0]vectors(
[0]
[0]attached=
[0]
[0]`H', spin_id=
[0]
[0]`@N')

If the attached atom is called `HN', type:


relax> structure.
[0]
[0]vectors(
[0]
[0]attached=
[0]
[0]`HN', spin_id=
[0]
[0]`@N')

For the `CA' spin bonded to the `HA' proton, type:


relax> structure.
[0]
[0]vectors(
[0]
[0]attached=
[0]
[0]`HA', spin_id=
[0]
[0]`@CA')

If you are working with RNA, you can use the residue name identifier to calculate the vectors for each residue separately. For example to calculate the vectors for all possible spins in the bases, type:


relax> structure.
[0]
[0]vectors(
[0]
[0]`H2', spin_id=
[0]
[0]`:A')


relax> structure.
[0]
[0]vectors(
[0]
[0]`H8', spin_id=
[0]
[0]`:A')


relax> structure.
[0]
[0]vectors(
[0]
[0]`H1', spin_id=
[0]
[0]`:G')


relax> structure.
[0]
[0]vectors(
[0]
[0]`H8', spin_id=
[0]
[0]`:G')


relax> structure.
[0]
[0]vectors(
[0]
[0]`H5', spin_id=
[0]
[0]`:C')


relax> structure.
[0]
[0]vectors(
[0]
[0]`H6', spin_id=
[0]
[0]`:C')


relax> structure.
[0]
[0]vectors(
[0]
[0]`H3', spin_id=
[0]
[0]`:U')


relax> structure.
[0]
[0]vectors(
[0]
[0]`H5', spin_id=
[0]
[0]`:U')


relax> structure.
[0]
[0]vectors(
[0]
[0]`H6', spin_id=
[0]
[0]`:U')

Alternatively, assuming the desired spins have been loaded, regular expression can be used:


relax> structure.
[0]
[0]vectors(
[0]
[0]`H*')





10.2.175 structure.write_pdb()

10.2.175.1 Synopsis

The PDB writing function.

10.2.175.2 Defaults

structure.
[0]write_pdb
(
[0]self, file=
[0]None, dir=
[0]None, model_num=
[0]None, force=
[0]False)

10.2.175.3 Keyword Arguments

file: The name of the PDB file.

dir: The directory where the file is located.

model_num: The optional model to place in the PDB file.

force: A flag which, if set to True, will overwrite the any pre-existing file.

10.2.175.4 Description

If the model_num argument is None, then all models will be written to a single file.

10.2.175.5 Example

To write all models and molecules to the PDB file `ensemble.pdb' within the directory `~/pdb', type one of:


relax> structure.
[0]
[0]write_pdb(
[0]
[0]`ensemble.
[0]
[0]pdb', `~/pdb')


relax> structure.
[0]
[0]write_pdb(
[0]
[0]file=
[0]
[0]`ensemble.
[0]
[0]pdb', dir=
[0]
[0]`pdb')

To write model number 3 into the new file `test.pdb', use one of:


relax> structure.
[0]
[0]write_pdb(
[0]
[0]`test.
[0]
[0]pdb', model_num=
[0]
[0]3)


relax> structure.
[0]
[0]write_pdb(
[0]
[0]file=
[0]
[0]`test.
[0]
[0]pdb', model_num=
[0]
[0]3)





10.2.176 system()

10.2.176.1 Synopsis

Function which executes the user supplied shell command.

10.2.176.2 Defaults

system(
[0]command)





10.2.177 temperature()

10.2.177.1 Synopsis

Specify the temperature of an experiment.

10.2.177.2 Defaults

temperature(
[0]self, id=
[0]None, temp=
[0]None)

10.2.177.3 Keyword arguments

id: The experiment identification string.

temp: The temperature of the experiment.

10.2.177.4 Description

This function allows the temperature of an experiment to be set. In certain analyses, for example those which use pseudocontact shift data, knowledge of the temperature is essential.





10.2.178 value.copy()

10.2.178.1 Synopsis

Copy spin specific data values from one data pipe to another.

10.2.178.2 Defaults

value.
[0]
[0]copy
(
[0]self, pipe_from=
[0]None, pipe_to=
[0]None, param=
[0]None)

10.2.178.3 Keyword Arguments

pipe_from: The name of the pipe to copy from.

pipe_to: The name of the pipe to copy to.

param: The parameter to copy.

10.2.178.4 Description

Only one parameter may be selected, therefore the `param' argument should be a string.

If this function is used to change values of previously minimised parameters, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.

10.2.178.5 Examples

To copy the CSA values from the data pipe `m1' to `m2', type:


relax> value.
[0]
[0]
[0]copy(
[0]
[0]`m1', `m2', `CSA')


10.2.178.6 Regular expression

The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.

This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:

`[]' -
A sequence or set of characters to match to a single character. For example, `[Ss]2' will match both `S2' and `s2'.
`^' -
Match the start of the string.
`$' -
Match the end of the string. For example, `^[Ss]2$' will match `s2' but not `S2f' or `s2s'.
`.' -
Match any character.
`x*' -
Match the character `x' any number of times, for example `x' will match, as will `xxxxx'
`.*' -
Match any sequence of characters of any length.

Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.

10.2.178.7 Model-free set details

Setting a parameter value may have no effect depending on which model-free model is chosen, for example if $ S^2_f$ values and $ S^2_s$ values are set but the run corresponds to model-free model `m4' then, because these data values are not parameters of the model, they will have no effect.

Note that the $ R_{ex}$ values are scaled quadratically with field strength and should be supplied as a field strength independent value. Use the following formula to get the correct value:

value = $ R_{ex}$ / (2.0 * $ \pi$ * frequency) ** 2

where:

$ R_{ex}$ is the chemical exchange value for the current frequency.
$ \pi$ is in the namespace of relax, ie just type `pi'.
frequency is the proton frequency corresponding to the data.

10.2.178.8 Model-free data type string matching patterns

(see table 10.25)

Table: First table for the value.copy() user function.
Data type Object name Patterns
Local $ \tau _m$ `local_tm' `[Ll]ocal[ -_]tm'
Order parameter $ S^2$ `s2' `^[Ss]2$'
Order parameter $ S^2_f$ `s2f' `^[Ss]2f$'
Order parameter $ S^2_s$ `s2s' `^[Ss]2s$'
Correlation time $ \tau _e$ `te' `^te$'
Correlation time $ \tau _f$ `tf' `^tf$'
Correlation time $ \tau _s$ `ts' `^ts$'
Chemical exchange `rex' `^[Rr]ex$' or `[Cc]emical[ -_][Ee]xchange'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'


10.2.178.9 Reduced spectral density mapping set details

In reduced spectral density mapping, three values must be set prior to the calculation of spectral density values: the bond length, CSA, and heteronucleus type.


10.2.178.10 Reduced spectral density mapping data type string matching patterns

(see table 10.26)

Table: Second table for the value.copy() user function.
Data type Object name Patterns
$ J(0)$ `j0' `^[Jj]0$' or `[Jj] $ \backslash$ (0 $ \backslash$ )'
$ J(\omega_X)$ `jwx' `^[Jj]w[Xx]$' or `[Jj] $ \backslash$ (w[Xx] $ \backslash$ )'
$ J(\omega_H)$ `jwh' `^[Jj]w[Hh]$' or `[Jj] $ \backslash$ (w[Hh] $ \backslash$ )'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'


10.2.178.11 Relaxation curve fitting set details

Only three parameters can be set, the relaxation rate (Rx), the initial intensity (I0), and the intensity at infinity (Iinf). Setting the parameter Iinf has no effect if the chosen model is that of the exponential curve which decays to zero.


10.2.178.12 Relaxation curve fitting data type string matching patterns

(see table 10.27)

Table: Third table for the value.copy() user function.
Data type Object name Patterns
Relaxation rate `rx' `^[Rr]x$'
Peak intensities (series) `intensities' `^[Ii]nt$'
Initial intensity `i0' `^[Ii]0$'
Intensity at infinity `iinf' `^[Ii]inf$'
Relaxation period times (series) `relax_times' `^[Rr]elax[ -_][Tt]imes$'

10.2.178.13 N-state model set details

Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states. To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be added to the end of the parameter name. So the Euler angle $ \gamma$ of the third state is specified using the string `gamma2'.

10.2.178.14 N-state model data type string matching patterns

(see table 10.28)

Table: Fourth table for the value.copy() user function.
Data type Object name Patterns
Probabilities `probs' `p0', `p1', `p2', ..., `pN'
Euler angle $ \alpha$ `alpha' `alpha0', `alpha1', ...
Euler angle $ \beta$ `beta' `beta0', `beta1', ...
Euler angle $ \gamma$ `gamma' `gamma0', `gamma1', ...
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'

The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.





10.2.179 value.display()

10.2.179.1 Synopsis

Display spin specific data values.

10.2.179.2 Defaults

value.
[0]
[0]display
(
[0]self, param=
[0]None)

10.2.179.3 Keyword Arguments

param: The parameter to display.

10.2.179.4 Description

Only one parameter may be selected, therefore the `param' argument should be a string.

10.2.179.5 Examples

To show all CSA values, type:


relax> value.
[0]
[0]
[0]display(
[0]
[0]`CSA')


10.2.179.6 Regular expression

The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.

This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:

`[]' -
A sequence or set of characters to match to a single character. For example, `[Ss]2' will match both `S2' and `s2'.
`^' -
Match the start of the string.
`$' -
Match the end of the string. For example, `^[Ss]2$' will match `s2' but not `S2f' or `s2s'.
`.' -
Match any character.
`x*' -
Match the character `x' any number of times, for example `x' will match, as will `xxxxx'
`.*' -
Match any sequence of characters of any length.

Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.

10.2.179.7 Model-free data type string matching patterns

(see table 10.29)

Table: First table for the value.display() user function.
Data type Object name Patterns
Local $ \tau _m$ `local_tm' `[Ll]ocal[ -_]tm'
Order parameter $ S^2$ `s2' `^[Ss]2$'
Order parameter $ S^2_f$ `s2f' `^[Ss]2f$'
Order parameter $ S^2_s$ `s2s' `^[Ss]2s$'
Correlation time $ \tau _e$ `te' `^te$'
Correlation time $ \tau _f$ `tf' `^tf$'
Correlation time $ \tau _s$ `ts' `^ts$'
Chemical exchange `rex' `^[Rr]ex$' or `[Cc]emical[ -_][Ee]xchange'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'


10.2.179.8 Reduced spectral density mapping data type string matching patterns

(see table 10.30)

Table: Second table for the value.display() user function.
Data type Object name Patterns
$ J(0)$ `j0' `^[Jj]0$' or `[Jj] $ \backslash$ (0 $ \backslash$ )'
$ J(\omega_X)$ `jwx' `^[Jj]w[Xx]$' or `[Jj] $ \backslash$ (w[Xx] $ \backslash$ )'
$ J(\omega_H)$ `jwh' `^[Jj]w[Hh]$' or `[Jj] $ \backslash$ (w[Hh] $ \backslash$ )'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'


10.2.179.9 Relaxation curve fitting data type string matching patterns

(see table 10.31)

Table: Third table for the value.display() user function.
Data type Object name Patterns
Relaxation rate `rx' `^[Rr]x$'
Peak intensities (series) `intensities' `^[Ii]nt$'
Initial intensity `i0' `^[Ii]0$'
Intensity at infinity `iinf' `^[Ii]inf$'
Relaxation period times (series) `relax_times' `^[Rr]elax[ -_][Tt]imes$'

10.2.179.10 N-state model data type string matching patterns

(see table 10.32)

Table: Fourth table for the value.display() user function.
Data type Object name Patterns
Probabilities `probs' `p0', `p1', `p2', ..., `pN'
Euler angle $ \alpha$ `alpha' `alpha0', `alpha1', ...
Euler angle $ \beta$ `beta' `beta0', `beta1', ...
Euler angle $ \gamma$ `gamma' `gamma0', `gamma1', ...
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'

The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.





10.2.180 value.read()

10.2.180.1 Synopsis

Read spin specific data values from a file.

10.2.180.2 Defaults

value.
[0]read
(
[0]self, param=
[0]None, scaling=
[0]1.0, file=
[0]None, dir=
[0]None, spin_id_col=
[0]None, mol_name_col=
[0]None, res_num_col=
[0]None, res_name_col=
[0]None, spin_num_col=
[0]None, spin_name_col=
[0]None, data_col=
[0]None, error_col=
[0]None, sep=
[0]None, spin_id=
[0]None)

10.2.180.3 Keyword Arguments

param: The parameter.

scaling: The factor to scale parameters by.

file: The name of the file containing the values.

dir: The directory where the file is located.

spin_id_col: The spin ID string column (an alternative to the mol, res, and spin name and number columns).

mol_name_col: The molecule name column (alternative to the spin_id_col).

res_num_col: The residue number column (alternative to the spin_id_col).

res_name_col: The residue name column (alternative to the spin_id_col).

spin_num_col: The spin number column (alternative to the spin_id_col).

spin_name_col: The spin name column (alternative to the spin_id_col).

data_col: The RDC data column.

error_col: The experimental error column.

sep: The column separator (the default is white space).

spin_id: The spin ID string to restrict the loading of data to certain spin subsets.

10.2.180.4 Description

The spin system can be identified in the file using two different formats. The first is the spin ID string column which can include the molecule name, the residue name and number, and the spin name and number. Alternatively the mol_name_col, res_num_col, res_name_col, spin_num_col, and/or spin_name_col arguments can be supplied allowing this information to be in separate columns. Note that the numbering of columns starts at one. The spin_id argument can be used to restrict the reading to certain spin types, for example only 15N spins when only residue information is in the file.

Only one parameter may be selected, therefore the `param' argument should be a string.

If this function is used to change values of previously minimised parameters, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset.

10.2.180.5 Examples

To load 15N CSA values from the file `csa_values' in the directory `data', where spins are only identified by residue name and number, type one of the following:


relax> value.
[0]
[0]read(
[0]
[0]`CSA', `data/csa_value', spin_id=
[0]
[0]`@N')


relax> value.
[0]
[0]read(
[0]
[0]`CSA', `csa_value', dir=
[0]
[0]`data', spin_id=
[0]
[0]`@N')


relax> value.
[0]
[0]read(
[0]
[0]param=
[0]
[0]`CSA', file=
[0]
[0]`csa_value', dir=
[0]
[0]`data', res_num_col=
[0]
[0]1, res_name_col=
[0]
[0]2, data_col=
[0]
[0]3, error_col=
[0]
[0]4, spin_id=
[0]
[0]`@N')


10.2.180.6 Regular expression

The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.

This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:

`[]' -
A sequence or set of characters to match to a single character. For example, `[Ss]2' will match both `S2' and `s2'.
`^' -
Match the start of the string.
`$' -
Match the end of the string. For example, `^[Ss]2$' will match `s2' but not `S2f' or `s2s'.
`.' -
Match any character.
`x*' -
Match the character `x' any number of times, for example `x' will match, as will `xxxxx'
`.*' -
Match any sequence of characters of any length.

Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.

10.2.180.7 Model-free set details

Setting a parameter value may have no effect depending on which model-free model is chosen, for example if $ S^2_f$ values and $ S^2_s$ values are set but the run corresponds to model-free model `m4' then, because these data values are not parameters of the model, they will have no effect.

Note that the $ R_{ex}$ values are scaled quadratically with field strength and should be supplied as a field strength independent value. Use the following formula to get the correct value:

value = $ R_{ex}$ / (2.0 * $ \pi$ * frequency) ** 2

where:

$ R_{ex}$ is the chemical exchange value for the current frequency.
$ \pi$ is in the namespace of relax, ie just type `pi'.
frequency is the proton frequency corresponding to the data.

10.2.180.8 Model-free data type string matching patterns

(see table 10.33)

Table: First table for the value.read() user function.
Data type Object name Patterns
Local $ \tau _m$ `local_tm' `[Ll]ocal[ -_]tm'
Order parameter $ S^2$ `s2' `^[Ss]2$'
Order parameter $ S^2_f$ `s2f' `^[Ss]2f$'
Order parameter $ S^2_s$ `s2s' `^[Ss]2s$'
Correlation time $ \tau _e$ `te' `^te$'
Correlation time $ \tau _f$ `tf' `^tf$'
Correlation time $ \tau _s$ `ts' `^ts$'
Chemical exchange `rex' `^[Rr]ex$' or `[Cc]emical[ -_][Ee]xchange'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'


10.2.180.9 Reduced spectral density mapping set details

In reduced spectral density mapping, three values must be set prior to the calculation of spectral density values: the bond length, CSA, and heteronucleus type.


10.2.180.10 Reduced spectral density mapping data type string matching patterns

(see table 10.34)

Table: Second table for the value.read() user function.
Data type Object name Patterns
$ J(0)$ `j0' `^[Jj]0$' or `[Jj] $ \backslash$ (0 $ \backslash$ )'
$ J(\omega_X)$ `jwx' `^[Jj]w[Xx]$' or `[Jj] $ \backslash$ (w[Xx] $ \backslash$ )'
$ J(\omega_H)$ `jwh' `^[Jj]w[Hh]$' or `[Jj] $ \backslash$ (w[Hh] $ \backslash$ )'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'


10.2.180.11 Relaxation curve fitting set details

Only three parameters can be set, the relaxation rate (Rx), the initial intensity (I0), and the intensity at infinity (Iinf). Setting the parameter Iinf has no effect if the chosen model is that of the exponential curve which decays to zero.


10.2.180.12 Relaxation curve fitting data type string matching patterns

(see table 10.35)

Table: Third table for the value.read() user function.
Data type Object name Patterns
Relaxation rate `rx' `^[Rr]x$'
Peak intensities (series) `intensities' `^[Ii]nt$'
Initial intensity `i0' `^[Ii]0$'
Intensity at infinity `iinf' `^[Ii]inf$'
Relaxation period times (series) `relax_times' `^[Rr]elax[ -_][Tt]imes$'

10.2.180.13 N-state model set details

Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states. To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be added to the end of the parameter name. So the Euler angle $ \gamma$ of the third state is specified using the string `gamma2'.

10.2.180.14 N-state model data type string matching patterns

(see table 10.36)

Table: Fourth table for the value.read() user function.
Data type Object name Patterns
Probabilities `probs' `p0', `p1', `p2', ..., `pN'
Euler angle $ \alpha$ `alpha' `alpha0', `alpha1', ...
Euler angle $ \beta$ `beta' `beta0', `beta1', ...
Euler angle $ \gamma$ `gamma' `gamma0', `gamma1', ...
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'

The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.





10.2.181 value.set()

10.2.181.1 Synopsis

Set spin specific data values.

10.2.181.2 Defaults

value.
[0]set
(
[0]self, val=
[0]None, param=
[0]None, spin_id=
[0]None)

10.2.181.3 Keyword arguments

val: The value(s).

param: The parameter(s).

spin_id: The spin identifier.

10.2.181.4 Description

If this function is used to change values of previously minimised results, then the minimisation statistics (chi-squared value, iteration count, function count, gradient count, and Hessian count) will be reset to None.

The val argument can be None, a single value, or an array of values while the parameter argument can be None, a string, or array of strings. The choice of which combination determines the behaviour of this function. The following table describes what occurs in each instance. The Value column refers to the `val' argument while the Param column refers to the `param' argument. In these columns, `None' corresponds to None, `1' corresponds to either a single value or single string, and `n' corresponds to either an array of values or an array of strings.

(see table 10.37)

Table: First table for the value.set() user function.
Value Param Description
None None This case is used to set the model parameters prior to minimisation or
calculation. The model parameters are set to the default values.
1 None Invalid combination.
$ n$ None This case is used to set the model parameters prior to minimisation or
calculation. The length of the val array must be equal to the number
of model parameters. The parameters will be set to the corresponding
number.
None 1 The parameter matching the string will be set to the default value.
1 1 The parameter matching the string will be set to the supplied number.
$ n$ 1 Invalid combination.
None $ n$ Each parameter matching the strings will be set to the default values.
1 $ n$ Each parameter matching the strings will be set to the supplied number.
$ n$ $ n$ Each parameter matching the strings will be set to the corresponding
number. Both arrays must be of equal length.

10.2.181.5 Spin identification

If the `spin_id' argument is left as the default of None, then the function will be applied to all spins. If the data is global non-spin specific data, such as diffusion tensor parameters, supplying the spin identifier will terminate the program with an error.

10.2.181.6 Examples

To set the parameter values for the current data pipe to the default values, for all spins, type:


relax> value.
[0]
[0]set(
[0]
[0])

To set the parameter values of residue 10, which is in the current model-free data pipe `m4' and has the parameters {$ S^2$ , $ \tau _e$ , $ R_{ex}$ }, the following can be used. $ R_{ex}$ term is the value for the first given field strength.


relax> value.
[0]
[0]set(
[0]
[0][0.97, 2.048*1e-9, 0.149], spin_id=
[0]
[0]`:10')


relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0][0.97, 2.048*1e-9, 0.149], spin_id=
[0]
[0]`:10')

To set the CSA value of all spins to the default value, type:


relax> value.
[0]
[0]set(
[0]
[0]param=
[0]
[0]`csa')

To set the CSA value of all spins to -172 ppm, type:


relax> value.
[0]
[0]set(
[0]
[0]-172 * 1e-6, `csa')


relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0]-172 * 1e-6, param=
[0]
[0]`csa')

To set the NH bond length of all spins to 1.02 Å, type:


relax> value.
[0]
[0]set(
[0]
[0]1.02 * 1e-10, `bond_length')


relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0]1.02 * 1e-10, param=
[0]
[0]`r')

To set both the bond length and the CSA value to the default values, type:


relax> value.
[0]
[0]set(
[0]
[0]param=
[0]
[0][`bond length', `csa'])

To set both $ \tau _f$ and $ \tau _s$ to 100 ps, type:


relax> value.
[0]
[0]set(
[0]
[0]100e-12, [`tf', `ts'])


relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0]100e-12, param=
[0]
[0][`tf', `ts'])

To set the $ S^2$ and $ \tau _e$ parameter values of residue 126, Ca spins to 0.56 and 13 ps, type:


relax> value.
[0]
[0]set(
[0]
[0][0.56, 13e-12], [`S2', `te'], `:126@Ca')


relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0][0.56, 13e-12], param=
[0]
[0][`S2', `te'], spin_id=
[0]
[0]`:126@Ca')


relax> value.
[0]
[0]set(
[0]
[0]val=
[0]
[0][0.56, 13e-12], param=
[0]
[0][`S2', `te'], spin_id=
[0]
[0]`:126@Ca')


10.2.181.7 Regular expression

The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.

This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:

`[]' -
A sequence or set of characters to match to a single character. For example, `[Ss]2' will match both `S2' and `s2'.
`^' -
Match the start of the string.
`$' -
Match the end of the string. For example, `^[Ss]2$' will match `s2' but not `S2f' or `s2s'.
`.' -
Match any character.
`x*' -
Match the character `x' any number of times, for example `x' will match, as will `xxxxx'
`.*' -
Match any sequence of characters of any length.

Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.

10.2.181.8 Model-free set details

Setting a parameter value may have no effect depending on which model-free model is chosen, for example if $ S^2_f$ values and $ S^2_s$ values are set but the run corresponds to model-free model `m4' then, because these data values are not parameters of the model, they will have no effect.

Note that the $ R_{ex}$ values are scaled quadratically with field strength and should be supplied as a field strength independent value. Use the following formula to get the correct value:

value = $ R_{ex}$ / (2.0 * $ \pi$ * frequency) ** 2

where:

$ R_{ex}$ is the chemical exchange value for the current frequency.
$ \pi$ is in the namespace of relax, ie just type `pi'.
frequency is the proton frequency corresponding to the data.

10.2.181.9 Model-free data type string matching patterns

(see table 10.38)

Table: Second table for the value.set() user function.
Data type Object name Patterns
Local $ \tau _m$ `local_tm' `[Ll]ocal[ -_]tm'
Order parameter $ S^2$ `s2' `^[Ss]2$'
Order parameter $ S^2_f$ `s2f' `^[Ss]2f$'
Order parameter $ S^2_s$ `s2s' `^[Ss]2s$'
Correlation time $ \tau _e$ `te' `^te$'
Correlation time $ \tau _f$ `tf' `^tf$'
Correlation time $ \tau _s$ `ts' `^ts$'
Chemical exchange `rex' `^[Rr]ex$' or `[Cc]emical[ -_][Ee]xchange'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'

10.2.181.10 Model-free default values

(see table 10.39)

Table: Third table for the value.set() user function.
Data type Object name Value
Local $ \tau _m$ `local_tm' 10 * 1e-9
Order parameters $ S^2$ , $ S^2_f$ , and $ S^2_s$ `s2', `s2f', `s2s' 0.8
Correlation time $ \tau _e$ `te' 100 * 1e-12
Correlation time $ \tau _f$ `tf' 10 * 1e-12
Correlation time $ \tau _s$ `ts' 1000 * 1e-12
Chemical exchange relaxation `rex' 0.0
Bond length `r' 1.02 * 1e-10
CSA `csa' -172 * 1e-6
Heteronucleus type `heteronuc_type' `15N'
Proton type `proton_type' `1H'


10.2.181.11 Reduced spectral density mapping set details

In reduced spectral density mapping, three values must be set prior to the calculation of spectral density values: the bond length, CSA, and heteronucleus type.


10.2.181.12 Reduced spectral density mapping data type string matching patterns

(see table 10.40)

Table: Fourth table for the value.set() user function.
Data type Object name Patterns
$ J(0)$ `j0' `^[Jj]0$' or `[Jj] $ \backslash$ (0 $ \backslash$ )'
$ J(\omega_X)$ `jwx' `^[Jj]w[Xx]$' or `[Jj] $ \backslash$ (w[Xx] $ \backslash$ )'
$ J(\omega_H)$ `jwh' `^[Jj]w[Hh]$' or `[Jj] $ \backslash$ (w[Hh] $ \backslash$ )'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'


10.2.181.13 Reduced spectral density mapping default values

(see table 10.41)

Table: Fifth table for the value.set() user function.
Data type Object name Value
Bond length `r' 1.02 * 1e-10
CSA `csa' -172 * 1e-6
Heteronucleus type `heteronuc_type' `15N'
Proton type `proton_type' `1H'


10.2.181.14 Diffusion tensor set details

If the diffusion tensor has not been setup, use the more powerful function `diffusion_tensor.init' to initialise the tensor parameters. This function cannot be used to initialise a diffusion tensor.

The units of the parameters are:

Inverse seconds for $ \tau _m$ .
Seconds for $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_a$ , $ \mathfrak{D}_x$ , $ \mathfrak{D}_y$ , $ \mathfrak{D}_z$ , $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ , $ \mathfrak{D}_{\scriptscriptstyle \perp}$ .
Unitless for $ \mathfrak{D}_{ratio}$ and $ \mathfrak{D}_r$ .
Radians for all angles ($ \alpha$ , $ \beta$ , $ \gamma$ , $ \theta$ , $ \phi$ ).

When setting a diffusion tensor parameter, the residue number has no effect. As the internal parameters of spherical diffusion are {tm}, spheroidal diffusion are {$ \tau _m$ , $ \mathfrak{D}_a$ , $ \theta$ , $ \phi$ }, and ellipsoidal diffusion are {$ \tau _m$ , $ \mathfrak{D}_a$ , $ \mathfrak{D}_r$ , $ \alpha$ , $ \beta$ , $ \gamma$ }, supplying geometric parameters must be done in the following way. If a single geometric parameter is supplied, it must be one of $ \tau _m$ , $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_a$ , $ \mathfrak{D}_r$ , or $ \mathfrak{D}_{ratio}$ . For the parameters $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ , $ \mathfrak{D}_{\scriptscriptstyle \perp}$ , $ \mathfrak{D}_x$ , $ \mathfrak{D}_y$ , and $ \mathfrak{D}_x$ , it is not possible to determine how to use the currently set values together with the supplied value to calculate the new internal parameters. For spheroidal diffusion, when supplying multiple geometric parameters, the set must belong to one of

{$ \tau _m$ , $ \mathfrak{D}_a$ },
{ $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_a$ },
{$ \tau _m$ , $ \mathfrak{D}_{ratio}$ },
{ $ \mathfrak{D}_{\scriptscriptstyle \parallel}$ , $ \mathfrak{D}_{\scriptscriptstyle \perp}$ },
{ $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_{ratio}$ },

where either $ \theta$ , $ \phi$ , or both orientational parameters can be additionally supplied. For ellipsoidal diffusion, again when supplying multiple geometric parameters, the set must belong to one of

{$ \tau _m$ , $ \mathfrak{D}_a$ , $ \mathfrak{D}_r$ },
{ $ \mathfrak{D}_{iso}$ , $ \mathfrak{D}_a$ , $ \mathfrak{D}_r$ },
{ $ \mathfrak{D}_x$ , $ \mathfrak{D}_y$ , $ \mathfrak{D}_z$ },

where any number of the orientational parameters, $ \alpha$ , $ \beta$ , or $ \gamma$ can be additionally supplied.


10.2.181.15 Diffusion tensor parameter string matching patterns

(see table 10.42)

Table: Sixth table for the value.set() user function.
Data type Object name Patterns
Global correlation time - $ \tau _m$ `tm' `^tm$'
Isotropic component of the diffusion tensor - $ \mathfrak{D}_{iso}$ `Diso' `[Dd]iso'
Anisotropic component of the diffusion tensor - $ \mathfrak{D}_a$ `Da' `[Dd]a'
Rhombic component of the diffusion tensor - $ \mathfrak{D}_r$ `Dr' `[Dd]r$'
Eigenvalue associated with the x-axis of the diffusion `Dx' `[Dd]x'
diffusion tensor - $ \mathfrak{D}_x$
Eigenvalue associated with the y-axis of the diffusion `Dy' `[Dd]y'
diffusion tensor - $ \mathfrak{D}_y$
Eigenvalue associated with the z-axis of the diffusion `Dz' `[Dd]z'
diffusion tensor - $ \mathfrak{D}_z$
Diffusion coefficient parallel to the major axis of `Dpar' `[Dd]par'
the spheroid diffusion tensor - $ \mathfrak{D}_{\scriptscriptstyle \parallel}$
Diffusion coefficient perpendicular to the major axis `Dper' `[Dd]per'
of the spheroid diffusion tensor - $ \mathfrak{D}_{\scriptscriptstyle \perp}$
Ratio of the parallel and perpendicular components of `Dratio' `[Dd]ratio'
the spheroid diffusion tensor - $ \mathfrak{D}_{ratio}$
The first Euler angle of the ellipsoid diffusion `alpha' `^a$' or `alpha'
tensor - $ \alpha$
The second Euler angle of the ellipsoid diffusion `beta' `^b$' or `beta'
tensor - $ \beta$
The third Euler angle of the ellipsoid diffusion `gamma' `^g$' or `gamma'
tensor - $ \gamma$
The polar angle defining the major axis of the `theta' `theta'
spheroid diffusion tensor - $ \theta$
The azimuthal angle defining the major axis of the `phi' `phi'
spheroid diffusion tensor - $ \phi$


10.2.181.16 Diffusion tensor parameter default values

(see table 10.43)

Table: Seventh table for the value.set() user function.
Data type Object name Value
$ \tau _m$ `tm' 10 * 1e-9
$ \mathfrak{D}_{iso}$ `Diso' 1.666 * 1e7
$ \mathfrak{D}_a$ `Da' 0.0
$ \mathfrak{D}_r$ `Dr' 0.0
$ \mathfrak{D}_x$ `Dx' 1.666 * 1e7
$ \mathfrak{D}_y$ `Dy' 1.666 * 1e7
$ \mathfrak{D}_z$ `Dz' 1.666 * 1e7
$ \mathfrak{D}_{\scriptscriptstyle \parallel}$ `Dpar' 1.666 * 1e7
$ \mathfrak{D}_{\scriptscriptstyle \perp}$ `Dper' 1.666 * 1e7
$ \mathfrak{D}_{ratio}$ `Dratio' 1.0
$ \alpha$ `alpha' 0.0
$ \beta$ `beta' 0.0
$ \gamma$ `gamma' 0.0
$ \theta$ `theta' 0.0
$ \phi$ `phi' 0.0


10.2.181.17 Relaxation curve fitting set details

Only three parameters can be set, the relaxation rate (Rx), the initial intensity (I0), and the intensity at infinity (Iinf). Setting the parameter Iinf has no effect if the chosen model is that of the exponential curve which decays to zero.


10.2.181.18 Relaxation curve fitting data type string matching patterns

(see table 10.44)

Table: Eighth table for the value.set() user function.
Data type Object name Patterns
Relaxation rate `rx' `^[Rr]x$'
Peak intensities (series) `intensities' `^[Ii]nt$'
Initial intensity `i0' `^[Ii]0$'
Intensity at infinity `iinf' `^[Ii]inf$'
Relaxation period times (series) `relax_times' `^[Rr]elax[ -_][Tt]imes$'


10.2.181.19 Relaxation curve fitting default values

These values are completely arbitrary as peak heights (or volumes) are extremely variable and the Rx value is a compensation for both the R$ _1$ and R$ _2$ values.

(see table 10.45)

Table: Ninth table for the value.set() user function.
Data type Object name Value
Relaxation rate `rx' 8.0
Initial intensity `i0' 10000.0
Intensity at infinity `iinf' 0.0

10.2.181.20 N-state model set details

Setting parameters for the N-state model is a little different from the other type of analyses as each state has a set of parameters with the same names as the other states. To set the parameters for a specific state c (ranging from 0 for the first to N-1 for the last, the number c should be added to the end of the parameter name. So the Euler angle $ \gamma$ of the third state is specified using the string `gamma2'.

10.2.181.21 N-state model data type string matching patterns

(see table 10.46)

Table: Tenth table for the value.set() user function.
Data type Object name Patterns
Probabilities `probs' `p0', `p1', `p2', ..., `pN'
Euler angle $ \alpha$ `alpha' `alpha0', `alpha1', ...
Euler angle $ \beta$ `beta' `beta0', `beta1', ...
Euler angle $ \gamma$ `gamma' `gamma0', `gamma1', ...
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'

The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.

10.2.181.22 N-state model default values

(see table 10.47)

Table: Eleventh table for the value.set() user function.
Data type Object name Value
Probabilities `p0', `p1', `p2', ..., `pN' 1/N
Euler angle $ \alpha$ `alpha0', `alpha1', ... (c+1) * $ \pi$ / (N+1)
Euler angle $ \beta$ `beta0', `beta1', ... (c+1) * $ \pi$ / (N+1)
Euler angle $ \gamma$ `gamma0', `gamma1', ... (c+1) * $ \pi$ / (N+1)

In this table, N is the total number of states and c is the index of a given state ranging from 0 to N-1. The default probabilities are all set to be equal whereas the angles are given a range of values so that no 2 states are equal at the start of optimisation.

Note that setting the probability for state N will do nothing as it is equal to one minus all the other probabilities.





10.2.182 value.write()

10.2.182.1 Synopsis

Write spin specific data values to a file.

10.2.182.2 Defaults

value.
[0]write
(
[0]self, param=
[0]None, file=
[0]None, dir=
[0]None, bc=
[0]False, force=
[0]False)

10.2.182.3 Keyword Arguments

param: The parameter.

file: The name of the file.

dir: The directory name.

bc: A flag which if True will cause the back calculated values to be written to file rather than the actual data.

force: A flag which, if set to True, will cause the file to be overwritten.

10.2.182.4 Description

If no directory name is given, the file will be placed in the current working directory.

The parameter argument should be a string.

10.2.182.5 Examples

To write the CSA values to the file `csa.txt', type one of:


relax> value.
[0]
[0]write(
[0]
[0]`CSA', `csa.
[0]
[0]txt')


relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`CSA', file=
[0]
[0]`csa.
[0]
[0]txt')

To write the NOE values to the file `noe', type one of:


relax> value.
[0]
[0]write(
[0]
[0]`noe', `noe.
[0]
[0]out')


relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]out')


relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]out')


relax> value.
[0]
[0]write(
[0]
[0]param=
[0]
[0]`noe', file=
[0]
[0]`noe.
[0]
[0]out', force=
[0]
[0]True)


10.2.182.6 Regular expression

The python function `match', which uses regular expression, is used to determine which data type to set values to, therefore various data_type strings can be used to select the same data type. Patterns used for matching for specific data types are listed below.

This is a short description of python regular expression, for more information see the regular expression syntax section of the Python Library Reference. Some of the regular expression syntax used in this function is:

`[]' -
A sequence or set of characters to match to a single character. For example, `[Ss]2' will match both `S2' and `s2'.
`^' -
Match the start of the string.
`$' -
Match the end of the string. For example, `^[Ss]2$' will match `s2' but not `S2f' or `s2s'.
`.' -
Match any character.
`x*' -
Match the character `x' any number of times, for example `x' will match, as will `xxxxx'
`.*' -
Match any sequence of characters of any length.

Importantly, do not supply a string for the data type containing regular expression. The regular expression is implemented so that various strings can be supplied which all match the same data type.

10.2.182.7 Model-free data type string matching patterns

(see table 10.48)

Table: First table for the value.write() user function.
Data type Object name Patterns
Local $ \tau _m$ `local_tm' `[Ll]ocal[ -_]tm'
Order parameter $ S^2$ `s2' `^[Ss]2$'
Order parameter $ S^2_f$ `s2f' `^[Ss]2f$'
Order parameter $ S^2_s$ `s2s' `^[Ss]2s$'
Correlation time $ \tau _e$ `te' `^te$'
Correlation time $ \tau _f$ `tf' `^tf$'
Correlation time $ \tau _s$ `ts' `^ts$'
Chemical exchange `rex' `^[Rr]ex$' or `[Cc]emical[ -_][Ee]xchange'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'


10.2.182.8 Reduced spectral density mapping data type string matching patterns

(see table 10.49)

Table: Second table for the value.write() user function.
Data type Object name Patterns
$ J(0)$ `j0' `^[Jj]0$' or `[Jj] $ \backslash$ (0 $ \backslash$ )'
$ J(\omega_X)$ `jwx' `^[Jj]w[Xx]$' or `[Jj] $ \backslash$ (w[Xx] $ \backslash$ )'
$ J(\omega_H)$ `jwh' `^[Jj]w[Hh]$' or `[Jj] $ \backslash$ (w[Hh] $ \backslash$ )'
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
CSA `csa' `^[Cc][Ss][Aa]$'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'

10.2.182.9 NOE calculation data type string matching patterns

(see table 10.50)

Table: Third table for the value.write() user function.
Data type Object name Patterns
Reference intensity `ref' `^[Rr]ef$' or `[Rr]ef[ -_][Ii]nt'
Saturated intensity `sat' `^[Ss]at$' or `[Ss]at[ -_][Ii]nt'
NOE `noe' `^[Nn][Oo][Ee]$'


10.2.182.10 Relaxation curve fitting data type string matching patterns

(see table 10.51)

Table: Fourth table for the value.write() user function.
Data type Object name Patterns
Relaxation rate `rx' `^[Rr]x$'
Peak intensities (series) `intensities' `^[Ii]nt$'
Initial intensity `i0' `^[Ii]0$'
Intensity at infinity `iinf' `^[Ii]inf$'
Relaxation period times (series) `relax_times' `^[Rr]elax[ -_][Tt]imes$'

10.2.182.11 N-state model data type string matching patterns

(see table 10.52)

Table: Fifth table for the value.write() user function.
Data type Object name Patterns
Probabilities `probs' `p0', `p1', `p2', ..., `pN'
Euler angle $ \alpha$ `alpha' `alpha0', `alpha1', ...
Euler angle $ \beta$ `beta' `beta0', `beta1', ...
Euler angle $ \gamma$ `gamma' `gamma0', `gamma1', ...
Bond length `r' `^r$' or `[Bb]ond[ -_][Ll]ength'
Heteronucleus type `heteronuc_type' `^[Hh]eteronucleus$'
Proton type `proton_type' `^[Pp]roton$'

The objects corresponding to the object names are lists (or arrays) with each element corrsponding to each state.





10.2.183 vmd.view()

10.2.183.1 Synopsis

Function for viewing the collection of molecules extracted from the PDB file.

10.2.183.2 Defaults

vmd.
[0]view
(
[0]self)

10.2.183.3 Example


relax> vmd.
[0]
[0]view(
[0]
[0])

Edward d'Auvergne 2011-08-12